Freelog 22

home *** CD-ROM | disk | FTP | other *** search

/ Freelog 22 / freelog 22.iso / Prog / Djgpp / DJDEV203.ZIP / info / libc.info < prev next >

Wrap

GNU Info File | 2000-01-05 | 811.1 KB | 35,933 lines

This is Info file ../../info/libc.info, produced by Makeinfo version 1.68 from the input file libc.tex. This is the reference manual for libc.a Copyright (c) 1996 DJ Delorie File: libc.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) * Menu: * Introduction:: * Functional Categories:: All public symbols listed by category * Alphabetical List:: All public symbols in alphabetical order * Unimplemented:: Compatibility functions that either always fail or do nothing * Master Index:: File: libc.info, Node: Introduction, Next: Functional Categories, Prev: Top, Up: Top Introduction ************ The standard C library, `libc.a', is automatically linked into your programs by the `gcc' control program. It provides many of the functions that are normally associated with C programs. This document gives the proper usage information about each of the functions and variables found in `libc.a'. For each function or variable that the library provides, the definition of that symbol will include information on which header files to include in your source to obtain prototypes and type definitions relevant to the use of that symbol. Note that many of the functions in `libm.a' (the math library) are defined in `math.h' but are not present in libc.a. Some are, which may get confusing, but the rule of thumb is this--the C library contains those functions that ANSI dictates must exist, so that you don't need the `-lm' if you only use ANSI functions. In contrast, `libm.a' contains more functions and supports additional functionality such as the `matherr' call-back and compliance to several alternative standards of behavior in case of FP errors. *Note libm::, for more details. Debugging support functions are in the library `libdbg.a'; link your program with `-ldbg' to use them. File: libc.info, Node: Functional Categories, Next: Alphabetical List, Prev: Introduction, Up: Top Functional Categories ********************* * Menu: * bios functions:: * conio functions:: * cpu functions:: * ctype functions:: * debugging functions:: * dos functions:: * dpmi functions:: * environment functions:: * file system functions:: * go32 functions:: * io functions:: * locale functions:: * math functions:: * memory functions:: * misc functions:: * mono functions:: * posix functions:: * process functions:: * random number functions:: * shell functions:: * signal functions:: * sound functions:: * startup functions:: * stdio functions:: * string functions:: * termios functions:: * time functions:: * unix functions:: File: libc.info, Node: bios functions, Next: conio functions, Up: Functional Categories bios functions ============== * Menu: * _bios_disk:: * _bios_equiplist:: * _bios_keybrd:: * _bios_memsize:: * _bios_printer:: * _bios_serialcom:: * _bios_timeofday:: * bioscom:: * biosdisk:: * biosequip:: * bioskey:: * biosmemory:: * biosprint:: * biostime:: * getkey:: * getxkey:: * kbhit:: File: libc.info, Node: conio functions, Next: cpu functions, Prev: bios functions, Up: Functional Categories conio functions =============== * Menu: * blinkvideo:: * cgets:: * clreol:: * clrscr:: * _conio_kbhit:: * cprintf:: * cputs:: * cscanf:: * delline:: * getch:: * getche:: * gettext:: * gettextinfo:: * gotoxy:: * gppconio_init:: * highvideo:: * insline:: * intensevideo:: * lowvideo:: * movetext:: * normvideo:: * putch:: * puttext:: * Screen Variables:: * ScreenClear:: * ScreenCols:: * ScreenGetChar:: * ScreenGetCursor:: * ScreenMode:: * ScreenPutChar:: * ScreenPutString:: * ScreenRetrieve:: * ScreenRows:: * ScreenSetCursor:: * ScreenUpdate:: * ScreenUpdateLine:: * ScreenVisualBell:: * _set_screen_lines:: * _setcursortype:: * textattr:: * textbackground:: * textcolor:: * textmode:: * ungetch:: * wherex:: * wherey:: * window:: File: libc.info, Node: cpu functions, Next: ctype functions, Prev: conio functions, Up: Functional Categories cpu functions ============= * Menu: * _8087:: * _clear87:: * _control87:: * _detect_80387:: * disable:: * enable:: * _fpreset:: * htonl:: * htons:: * inb:: * inp:: * inportb:: * inportl:: * inportsb:: * inportsl:: * inportsw:: * inportw:: * inpw:: * _my_cs:: * _my_ds:: * _my_ss:: * ntohl:: * ntohs:: * outb:: * outp:: * outportb:: * outportl:: * outportsb:: * outportsl:: * outportsw:: * outportw:: * outpw:: * _status87:: File: libc.info, Node: ctype functions, Next: debugging functions, Prev: cpu functions, Up: Functional Categories ctype functions =============== * Menu: * isalnum:: * isalpha:: * isascii:: * iscntrl:: * isdigit:: * isgraph:: * islower:: * isprint:: * ispunct:: * isspace:: * isupper:: * isxdigit:: * toascii:: * tolower:: * toupper:: File: libc.info, Node: debugging functions, Next: dos functions, Prev: ctype functions, Up: Functional Categories debugging functions =================== * Menu: * cleanup_client:: * edi_init:: * load_npx:: * read_child:: * read_sel_addr:: * redir_cmdline_delete:: * redir_cmdline_parse:: * redir_debug_init:: * redir_to_child:: * redir_to_debugger:: * run_child:: * save_npx:: * syms_init:: * syms_line2val:: * syms_listwild:: * syms_module:: * syms_name2val:: * syms_val2line:: * syms_val2name:: * v2loadimage:: * wild:: * write_child:: * write_sel_addr:: File: libc.info, Node: dos functions, Next: dpmi functions, Prev: debugging functions, Up: Functional Categories dos functions ============= * Menu: * bdos:: * bdosptr:: * delay:: * _dos_close:: * _dos_commit:: * _dos_creat:: * _dos_creatnew:: * _dos_findfirst:: * _dos_findnext:: * _dos_getdate:: * _dos_getdiskfree:: * _dos_getdrive:: * _dos_getfileattr:: * _dos_getftime:: * _dos_gettime:: * _dos_lock:: * _dos_open:: * _dos_read:: * _dos_setdate:: * _dos_setdrive:: * _dos_setfileattr:: * _dos_setftime:: * _dos_settime:: * _dos_unlock:: * _dos_write:: * _doserrno:: * dosexterr:: * _flush_disk_cache:: * getcbrk:: * getdisk:: * int386:: * int386x:: * int86:: * int86x:: * intdos:: * intdosx:: * setcbrk:: * setdisk:: File: libc.info, Node: dpmi functions, Next: environment functions, Prev: dos functions, Up: Functional Categories dpmi functions ============== * Menu: * DPMI Overview:: * DPMI Specification:: * __dpmi_allocate_dos_memory:: * __dpmi_allocate_ldt_descriptors:: * __dpmi_allocate_linear_memory:: * __dpmi_allocate_memory:: * __dpmi_allocate_real_mode_callback:: * __dpmi_allocate_shared_memory:: * __dpmi_allocate_specific_ldt_descriptor:: * __dpmi_clear_debug_watchpoint:: * __dpmi_create_alias_descriptor:: * __dpmi_discard_page_contents:: * __dpmi_free_dos_memory:: * __dpmi_free_ldt_descriptor:: * __dpmi_free_memory:: * __dpmi_free_physical_address_mapping:: * __dpmi_free_real_mode_callback:: * __dpmi_free_serialization_on_shared_memory:: * __dpmi_free_shared_memory:: * __dpmi_get_and_disable_virtual_interrupt_state:: * __dpmi_get_and_enable_virtual_interrupt_state:: * __dpmi_get_and_set_virtual_interrupt_state:: * __dpmi_get_capabilities:: * __dpmi_get_coprocessor_status:: * __dpmi_get_descriptor:: * __dpmi_get_descriptor_access_rights:: * __dpmi_get_extended_exception_handler_vector_pm:: * __dpmi_get_extended_exception_handler_vector_rm:: * __dpmi_get_free_memory_information:: * __dpmi_get_memory_block_size_and_base:: * __dpmi_get_memory_information:: * __dpmi_get_multiple_descriptors:: * __dpmi_get_page_attributes:: * __dpmi_get_page_size:: * __dpmi_get_processor_exception_handler_vector:: * __dpmi_get_protected_mode_interrupt_vector:: * __dpmi_get_raw_mode_switch_addr:: * __dpmi_get_real_mode_interrupt_vector:: * __dpmi_get_segment_base_address:: * __dpmi_get_segment_limit:: * __dpmi_get_selector_increment_value:: * __dpmi_get_state_of_debug_watchpoint:: * __dpmi_get_state_save_restore_addr:: * __dpmi_get_vendor_specific_api_entry_point:: * __dpmi_get_version:: * __dpmi_get_virtual_interrupt_state:: * __dpmi_install_resident_service_provider_callback:: * __dpmi_int:: * __dpmi_lock_linear_region:: * __dpmi_map_conventional_memory_in_memory_block:: * __dpmi_map_device_in_memory_block:: * __dpmi_mark_page_as_demand_paging_candidate:: * __dpmi_mark_real_mode_region_as_pageable:: * __dpmi_physical_address_mapping:: * __dpmi_relock_real_mode_region:: * __dpmi_reset_debug_watchpoint:: * __dpmi_resize_dos_memory:: * __dpmi_resize_linear_memory:: * __dpmi_resize_memory:: * __dpmi_segment_to_descriptor:: * __dpmi_serialize_on_shared_memory:: * __dpmi_set_coprocessor_emulation:: * __dpmi_set_debug_watchpoint:: * __dpmi_set_descriptor:: * __dpmi_set_descriptor_access_rights:: * __dpmi_set_extended_exception_handler_vector_pm:: * __dpmi_set_extended_exception_handler_vector_rm:: * __dpmi_set_multiple_descriptors:: * __dpmi_set_page_attributes:: * __dpmi_set_processor_exception_handler_vector:: * __dpmi_set_protected_mode_interrupt_vector:: * __dpmi_set_real_mode_interrupt_vector:: * __dpmi_set_segment_base_address:: * __dpmi_set_segment_limit:: * __dpmi_simulate_real_mode_interrupt:: * __dpmi_simulate_real_mode_procedure_iret:: * __dpmi_simulate_real_mode_procedure_retf:: * __dpmi_simulate_real_mode_procedure_retf_stack:: * __dpmi_terminate_and_stay_resident:: * __dpmi_unlock_linear_region:: * __dpmi_yield:: * _go32_dpmi_allocate_dos_memory:: * _go32_dpmi_allocate_iret_wrapper:: * _go32_dpmi_allocate_real_mode_callback_iret:: * _go32_dpmi_allocate_real_mode_callback_retf:: * _go32_dpmi_chain_protected_mode_interrupt_vector:: * _go32_dpmi_free_dos_memory:: * _go32_dpmi_free_iret_wrapper:: * _go32_dpmi_free_real_mode_callback:: * _go32_dpmi_get_free_memory_information:: * _go32_dpmi_get_protected_mode_interrupt_vector:: * _go32_dpmi_get_real_mode_interrupt_vector:: * _go32_dpmi_remaining_physical_memory:: * _go32_dpmi_remaining_virtual_memory:: * _go32_dpmi_resize_dos_memory:: * _go32_dpmi_set_protected_mode_interrupt_vector:: * _go32_dpmi_set_real_mode_interrupt_vector:: * _go32_dpmi_simulate_fcall:: * _go32_dpmi_simulate_fcall_iret:: * _go32_dpmi_simulate_int:: * _go32_info_block:: File: libc.info, Node: environment functions, Next: file system functions, Prev: dpmi functions, Up: Functional Categories environment functions ===================== * Menu: * getenv:: * putenv:: * setenv:: File: libc.info, Node: file system functions, Next: go32 functions, Prev: environment functions, Up: Functional Categories file system functions ===================== * Menu: * access:: * basename:: * chdir:: * chmod:: * _chmod:: * _close:: * closedir:: * _creat:: * _creatnew:: * dirname:: * File System Extensions:: * __file_tree_walk:: * findfirst:: * findnext:: * _fixpath:: * fnmatch:: * fnmerge:: * fnsplit:: * fpathconf:: * __FSEXT_add_open_handler:: * __FSEXT_alloc_fd:: * __FSEXT_call_open_handlers:: * __FSEXT_get_data:: * __FSEXT_get_function:: * __FSEXT_set_data:: * __FSEXT_set_function:: * ftw:: * _get_volume_info:: * getcwd:: * getdfree:: * getftime:: * getwd:: * _invent_inode:: * _lfn_gen_short_fname:: * _lfn_get_ftime:: * mkdir:: * mkstemp:: * mktemp:: * _open:: * opendir:: * _preserve_fncase:: * _read:: * readdir:: * remove:: * _rename:: * rename:: * rewinddir:: * rmdir:: * searchpath:: * seekdir:: * setftime:: * statfs:: * telldir:: * tempnam:: * umask:: * unlink:: * _use_lfn:: * utime:: * _write:: File: libc.info, Node: go32 functions, Next: io functions, Prev: file system functions, Up: Functional Categories go32 functions ============== * Menu: * _go32_conventional_mem_selector:: * _go32_dpmi_lock_code:: * _go32_dpmi_lock_data:: * _go32_interrupt_stack_size:: * _go32_my_cs:: * _go32_my_ds:: * _go32_my_ss:: * _go32_rmcb_stack_size:: * _go32_want_ctrl_break:: * _go32_was_ctrl_break_hit:: File: libc.info, Node: io functions, Next: locale functions, Prev: go32 functions, Up: Functional Categories io functions ============ * Menu: * chsize:: * close:: * creat:: * crlf2nl:: * __djgpp_share_flags:: * dup:: * dup2:: * fcntl:: * __file_exists:: * filelength:: * _get_dev_info:: * ioctl (DOS):: * ioctl (General description):: * ioctl (UNIX):: * _is_executable:: * _is_remote_drive:: * _is_remote_handle:: * link:: * lock:: * lseek:: * open:: * _put_path:: * read:: * setmode:: * stat:: * symlink:: * tell:: * truncate:: * unlock:: * write:: File: libc.info, Node: locale functions, Next: math functions, Prev: io functions, Up: Functional Categories locale functions ================ * Menu: * localeconv:: * mblen:: * mbstowcs:: * mbtowc:: * setlocale:: * strcoll:: * strxfrm:: * wcstombs:: * wctomb:: File: libc.info, Node: math functions, Next: memory functions, Prev: locale functions, Up: Functional Categories math functions ============== * Menu: * abs:: * acos:: * acosh:: * asin:: * asinh:: * atan:: * atan2:: * atanh:: * cbrt:: * ceil:: * cos:: * cosh:: * div:: * exp:: * exp10:: * exp2:: * expm1:: * fabs:: * floor:: * fmod:: * frexp:: * hypot:: * ldexp:: * ldiv:: * libm:: * lldiv:: * log:: * log10:: * log1p:: * log2:: * matherr:: * modf:: * modfl:: * pow:: * pow10:: * pow2:: * powi:: * sin:: * sincos:: * sinh:: * sqrt:: * tan:: * tanh:: File: libc.info, Node: memory functions, Next: misc functions, Prev: math functions, Up: Functional Categories memory functions ================ * Menu: * alloca:: * bcmp:: * bcopy:: * brk:: * bzero:: * calloc:: * cfree:: * __djgpp_map_physical_memory:: * __djgpp_memory_handle:: * __djgpp_memory_handle_list:: * __djgpp_nearptr_disable:: * __djgpp_nearptr_enable:: * __djgpp_set_page_attributes:: * dosmemget:: * dosmemgetb:: * dosmemgetl:: * dosmemgetw:: * dosmemput:: * dosmemputb:: * dosmemputl:: * dosmemputw:: * _far*:: * free:: * malloc:: * memccpy:: * memchr:: * memcmp:: * memcpy:: * memicmp:: * memmove:: * memset:: * movedata:: * movedatab:: * movedatal:: * movedataw:: * mprotect:: * realloc:: * sbrk:: * stackavail:: * swab:: * xfree:: * xmalloc:: * xrealloc:: File: libc.info, Node: misc functions, Next: mono functions, Prev: memory functions, Up: Functional Categories misc functions ============== * Menu: * assert:: * bsearch:: * _dxe_load:: * _get_dos_version:: * gethostname:: * getlongpass:: * getopt:: * getpagesize:: * getpass:: * insque:: * labs:: * llabs:: * longjmp:: * qsort:: * remque:: * setjmp:: * siglongjmp:: * sigsetjmp:: * varargs:: File: libc.info, Node: mono functions, Next: posix functions, Prev: misc functions, Up: Functional Categories mono functions ============== * Menu: * _mono_clear:: * _mono_printf:: * _mono_putc:: File: libc.info, Node: posix functions, Next: process functions, Prev: mono functions, Up: Functional Categories posix functions =============== * Menu: * ctermid:: * getdtablesize:: * pathconf:: * sysconf:: File: libc.info, Node: process functions, Next: random number functions, Prev: posix functions, Up: Functional Categories process functions ================= * Menu: * abort:: * alarm:: * atexit:: * _check_v2_prog:: * exec*:: * __exit:: * _exit:: * exit:: * getitimer:: * kill:: * nice:: * pause:: * setitimer:: * sleep:: * spawn*:: * system:: * usleep:: * wait:: * waitpid:: File: libc.info, Node: random number functions, Next: shell functions, Prev: process functions, Up: Functional Categories random number functions ======================= * Menu: * initstate:: * rand:: * rand48:: * random:: * setstate:: * srand:: * srandom:: File: libc.info, Node: shell functions, Next: signal functions, Prev: random number functions, Up: Functional Categories shell functions =============== * Menu: * glob:: * globfree:: File: libc.info, Node: signal functions, Next: sound functions, Prev: shell functions, Up: Functional Categories signal functions ================ * Menu: * __djgpp_exception_toggle:: * __djgpp_set_ctrl_c:: * __djgpp_set_sigint_key:: * __djgpp_set_sigquit_key:: * __djgpp_traceback_exit:: * psignal:: * raise:: * sigaction:: * sigaddset:: * sigdelset:: * sigemptyset:: * sigfillset:: * sigismember:: * signal:: * sigpending:: * sigprocmask:: File: libc.info, Node: sound functions, Next: startup functions, Prev: signal functions, Up: Functional Categories sound functions =============== * Menu: * nosound:: * sound:: File: libc.info, Node: startup functions, Next: stdio functions, Prev: sound functions, Up: Functional Categories startup functions ================= * Menu: * __crt0_glob_function:: * __crt0_load_environment_file:: * __crt0_setup_arguments:: * _crt0_startup_flags:: * _stklen:: File: libc.info, Node: stdio functions, Next: string functions, Prev: startup functions, Up: Functional Categories stdio functions =============== * Menu: * clearerr:: * _djstat_describe_lossage:: * _djstat_fail_bits:: * _djstat_flags:: * _doprnt:: * _doscan:: * errno:: * fclose:: * fdopen:: * feof:: * ferror:: * fflush:: * fgetc:: * fgetpos:: * fgets:: * fileno:: * _fmode:: * fopen:: * fprintf:: * fpurge:: * fputc:: * fputs:: * fread:: * freopen:: * fscanf:: * fseek:: * fsetpos:: * fstat:: * fsync:: * ftell:: * ftruncate:: * _fwalk:: * fwrite:: * getc:: * getchar:: * gets:: * getw:: * perror:: * printf:: * putc:: * putchar:: * puts:: * putw:: * rewind:: * scanf:: * setbuf:: * setbuffer:: * setlinebuf:: * setvbuf:: * sprintf:: * sscanf:: * strerror:: * sys_errlist:: * sys_nerr:: * tmpfile:: * tmpnam:: * _truename:: * ungetc:: * vfprintf:: * vfscanf:: * vprintf:: * vscanf:: * vsprintf:: * vsscanf:: File: libc.info, Node: string functions, Next: termios functions, Prev: stdio functions, Up: Functional Categories string functions ================ * Menu: * atof:: * atoi:: * atol:: * _atold:: * ecvt:: * ecvtbuf:: * fcvt:: * fcvtbuf:: * ffs:: * gcvt:: * index:: * itoa:: * regcomp:: * regerror:: * regexec:: * regfree:: * rindex:: * stpcpy:: * strcasecmp:: * strcat:: * strchr:: * strcmp:: * strcpy:: * strcspn:: * strdup:: * stricmp:: * strlen:: * strlwr:: * strncasecmp:: * strncat:: * strncmp:: * strncpy:: * strnicmp:: * strpbrk:: * strrchr:: * strsep:: * strspn:: * strstr:: * strtod:: * strtok:: * strtol:: * _strtold:: * strtoll:: * strtoul:: * strtoull:: * strupr:: File: libc.info, Node: termios functions, Next: time functions, Prev: string functions, Up: Functional Categories termios functions ================= * Menu: * cfgetispeed:: * cfgetospeed:: * cfmakeraw:: * cfsetispeed:: * cfsetospeed:: * cfsetspeed:: * __libc_termios_init:: * tcdrain:: * tcflow:: * tcflush:: * tcgetattr:: * tcgetpgrp:: * tcsendbreak:: * tcsetattr:: * tcsetpgrp:: * Termios functions:: File: libc.info, Node: time functions, Next: unix functions, Prev: termios functions, Up: Functional Categories time functions ============== * Menu: * asctime:: * clock:: * ctime:: * difftime:: * ftime:: * getdate:: * gettime:: * gettimeofday:: * gmtime:: * localtime:: * mktime:: * rawclock:: * setdate:: * settime:: * settimeofday:: * strftime:: * time:: * times:: * tzset:: * tzsetwall:: * uclock:: * utimes:: File: libc.info, Node: unix functions, Prev: time functions, Up: Functional Categories unix functions ============== * Menu: * addmntent:: * chown:: * endgrent:: * endmntent:: * endpwent:: * fgetgrent:: * fork:: * getegid:: * geteuid:: * getgid:: * getgrent:: * getgrgid:: * getgrnam:: * getgroups:: * getlogin:: * getmntent:: * getpgrp:: * getpid:: * getpwent:: * getpwnam:: * getpwuid:: * getrlimit:: * getrusage:: * getuid:: * hasmntopt:: * isatty:: * mkfifo:: * mknod:: * pclose:: * pipe:: * popen:: * select:: * setgid:: * setgrent:: * setmntent:: * setpgid:: * setpwent:: * setrlimit:: * setsid:: * setuid:: * sync:: * ttyname:: * uname:: * vfork:: File: libc.info, Node: Alphabetical List, Next: Unimplemented, Prev: Functional Categories, Up: Top Alphabetical List ***************** * Menu: * _8087:: * abort:: * abs:: * access:: * acos:: * acosh:: * addmntent:: * alarm:: * alloca:: * asctime:: * asin:: * asinh:: * assert:: * atan:: * atan2:: * atanh:: * atexit:: * atof:: * atoi:: * atol:: * _atold:: * basename:: * bcmp:: * bcopy:: * bdos:: * bdosptr:: * _bios_disk:: * _bios_equiplist:: * _bios_keybrd:: * _bios_memsize:: * _bios_printer:: * _bios_serialcom:: * _bios_timeofday:: * bioscom:: * biosdisk:: * biosequip:: * bioskey:: * biosmemory:: * biosprint:: * biostime:: * blinkvideo:: * brk:: * bsearch:: * bzero:: * calloc:: * cbrt:: * ceil:: * cfgetispeed:: * cfgetospeed:: * cfmakeraw:: * cfree:: * cfsetispeed:: * cfsetospeed:: * cfsetspeed:: * cgets:: * chdir:: * _check_v2_prog:: * chmod:: * _chmod:: * chown:: * chsize:: * cleanup_client:: * _clear87:: * clearerr:: * clock:: * close:: * _close:: * closedir:: * clreol:: * clrscr:: * _conio_kbhit:: * _control87:: * cos:: * cosh:: * cprintf:: * cputs:: * creat:: * _creat:: * _creatnew:: * crlf2nl:: * __crt0_glob_function:: * __crt0_load_environment_file:: * __crt0_setup_arguments:: * _crt0_startup_flags:: * cscanf:: * ctermid:: * ctime:: * delay:: * delline:: * _detect_80387:: * difftime:: * dirname:: * disable:: * div:: * __djgpp_exception_toggle:: * __djgpp_map_physical_memory:: * __djgpp_memory_handle:: * __djgpp_memory_handle_list:: * __djgpp_nearptr_disable:: * __djgpp_nearptr_enable:: * __djgpp_set_ctrl_c:: * __djgpp_set_page_attributes:: * __djgpp_set_sigint_key:: * __djgpp_set_sigquit_key:: * __djgpp_share_flags:: * __djgpp_traceback_exit:: * _djstat_describe_lossage:: * _djstat_fail_bits:: * _djstat_flags:: * _doprnt:: * _dos_close:: * _dos_commit:: * _dos_creat:: * _dos_creatnew:: * _dos_findfirst:: * _dos_findnext:: * _dos_getdate:: * _dos_getdiskfree:: * _dos_getdrive:: * _dos_getfileattr:: * _dos_getftime:: * _dos_gettime:: * _dos_lock:: * _dos_open:: * _dos_read:: * _dos_setdate:: * _dos_setdrive:: * _dos_setfileattr:: * _dos_setftime:: * _dos_settime:: * _dos_unlock:: * _dos_write:: * _doscan:: * _doserrno:: * dosexterr:: * dosmemget:: * dosmemgetb:: * dosmemgetl:: * dosmemgetw:: * dosmemput:: * dosmemputb:: * dosmemputl:: * dosmemputw:: * DPMI Overview:: * DPMI Specification:: * __dpmi_allocate_dos_memory:: * __dpmi_allocate_ldt_descriptors:: * __dpmi_allocate_linear_memory:: * __dpmi_allocate_memory:: * __dpmi_allocate_real_mode_callback:: * __dpmi_allocate_shared_memory:: * __dpmi_allocate_specific_ldt_descriptor:: * __dpmi_clear_debug_watchpoint:: * __dpmi_create_alias_descriptor:: * __dpmi_discard_page_contents:: * __dpmi_free_dos_memory:: * __dpmi_free_ldt_descriptor:: * __dpmi_free_memory:: * __dpmi_free_physical_address_mapping:: * __dpmi_free_real_mode_callback:: * __dpmi_free_serialization_on_shared_memory:: * __dpmi_free_shared_memory:: * __dpmi_get_and_disable_virtual_interrupt_state:: * __dpmi_get_and_enable_virtual_interrupt_state:: * __dpmi_get_and_set_virtual_interrupt_state:: * __dpmi_get_capabilities:: * __dpmi_get_coprocessor_status:: * __dpmi_get_descriptor:: * __dpmi_get_descriptor_access_rights:: * __dpmi_get_extended_exception_handler_vector_pm:: * __dpmi_get_extended_exception_handler_vector_rm:: * __dpmi_get_free_memory_information:: * __dpmi_get_memory_block_size_and_base:: * __dpmi_get_memory_information:: * __dpmi_get_multiple_descriptors:: * __dpmi_get_page_attributes:: * __dpmi_get_page_size:: * __dpmi_get_processor_exception_handler_vector:: * __dpmi_get_protected_mode_interrupt_vector:: * __dpmi_get_raw_mode_switch_addr:: * __dpmi_get_real_mode_interrupt_vector:: * __dpmi_get_segment_base_address:: * __dpmi_get_segment_limit:: * __dpmi_get_selector_increment_value:: * __dpmi_get_state_of_debug_watchpoint:: * __dpmi_get_state_save_restore_addr:: * __dpmi_get_vendor_specific_api_entry_point:: * __dpmi_get_version:: * __dpmi_get_virtual_interrupt_state:: * __dpmi_install_resident_service_provider_callback:: * __dpmi_int:: * __dpmi_lock_linear_region:: * __dpmi_map_conventional_memory_in_memory_block:: * __dpmi_map_device_in_memory_block:: * __dpmi_mark_page_as_demand_paging_candidate:: * __dpmi_mark_real_mode_region_as_pageable:: * __dpmi_physical_address_mapping:: * __dpmi_relock_real_mode_region:: * __dpmi_reset_debug_watchpoint:: * __dpmi_resize_dos_memory:: * __dpmi_resize_linear_memory:: * __dpmi_resize_memory:: * __dpmi_segment_to_descriptor:: * __dpmi_serialize_on_shared_memory:: * __dpmi_set_coprocessor_emulation:: * __dpmi_set_debug_watchpoint:: * __dpmi_set_descriptor:: * __dpmi_set_descriptor_access_rights:: * __dpmi_set_extended_exception_handler_vector_pm:: * __dpmi_set_extended_exception_handler_vector_rm:: * __dpmi_set_multiple_descriptors:: * __dpmi_set_page_attributes:: * __dpmi_set_processor_exception_handler_vector:: * __dpmi_set_protected_mode_interrupt_vector:: * __dpmi_set_real_mode_interrupt_vector:: * __dpmi_set_segment_base_address:: * __dpmi_set_segment_limit:: * __dpmi_simulate_real_mode_interrupt:: * __dpmi_simulate_real_mode_procedure_iret:: * __dpmi_simulate_real_mode_procedure_retf:: * __dpmi_simulate_real_mode_procedure_retf_stack:: * __dpmi_terminate_and_stay_resident:: * __dpmi_unlock_linear_region:: * __dpmi_yield:: * dup:: * dup2:: * _dxe_load:: * ecvt:: * ecvtbuf:: * edi_init:: * enable:: * endgrent:: * endmntent:: * endpwent:: * errno:: * exec*:: * __exit:: * _exit:: * exit:: * exp:: * exp10:: * exp2:: * expm1:: * fabs:: * _far*:: * fclose:: * fcntl:: * fcvt:: * fcvtbuf:: * fdopen:: * feof:: * ferror:: * fflush:: * ffs:: * fgetc:: * fgetgrent:: * fgetpos:: * fgets:: * File System Extensions:: * __file_exists:: * __file_tree_walk:: * filelength:: * fileno:: * findfirst:: * findnext:: * _fixpath:: * floor:: * _flush_disk_cache:: * fmod:: * _fmode:: * fnmatch:: * fnmerge:: * fnsplit:: * fopen:: * fork:: * fpathconf:: * _fpreset:: * fprintf:: * fpurge:: * fputc:: * fputs:: * fread:: * free:: * freopen:: * frexp:: * fscanf:: * fseek:: * fsetpos:: * __FSEXT_add_open_handler:: * __FSEXT_alloc_fd:: * __FSEXT_call_open_handlers:: * __FSEXT_get_data:: * __FSEXT_get_function:: * __FSEXT_set_data:: * __FSEXT_set_function:: * fstat:: * fsync:: * ftell:: * ftime:: * ftruncate:: * ftw:: * _fwalk:: * fwrite:: * gcvt:: * _get_dev_info:: * _get_dos_version:: * _get_volume_info:: * getc:: * getcbrk:: * getch:: * getchar:: * getche:: * getcwd:: * getdate:: * getdfree:: * getdisk:: * getdtablesize:: * getegid:: * getenv:: * geteuid:: * getftime:: * getgid:: * getgrent:: * getgrgid:: * getgrnam:: * getgroups:: * gethostname:: * getitimer:: * getkey:: * getlogin:: * getlongpass:: * getmntent:: * getopt:: * getpagesize:: * getpass:: * getpgrp:: * getpid:: * getpwent:: * getpwnam:: * getpwuid:: * getrlimit:: * getrusage:: * gets:: * gettext:: * gettextinfo:: * gettime:: * gettimeofday:: * getuid:: * getw:: * getwd:: * getxkey:: * glob:: * globfree:: * gmtime:: * _go32_conventional_mem_selector:: * _go32_dpmi_allocate_dos_memory:: * _go32_dpmi_allocate_iret_wrapper:: * _go32_dpmi_allocate_real_mode_callback_iret:: * _go32_dpmi_allocate_real_mode_callback_retf:: * _go32_dpmi_chain_protected_mode_interrupt_vector:: * _go32_dpmi_free_dos_memory:: * _go32_dpmi_free_iret_wrapper:: * _go32_dpmi_free_real_mode_callback:: * _go32_dpmi_get_free_memory_information:: * _go32_dpmi_get_protected_mode_interrupt_vector:: * _go32_dpmi_get_real_mode_interrupt_vector:: * _go32_dpmi_lock_code:: * _go32_dpmi_lock_data:: * _go32_dpmi_remaining_physical_memory:: * _go32_dpmi_remaining_virtual_memory:: * _go32_dpmi_resize_dos_memory:: * _go32_dpmi_set_protected_mode_interrupt_vector:: * _go32_dpmi_set_real_mode_interrupt_vector:: * _go32_dpmi_simulate_fcall:: * _go32_dpmi_simulate_fcall_iret:: * _go32_dpmi_simulate_int:: * _go32_info_block:: * _go32_interrupt_stack_size:: * _go32_my_cs:: * _go32_my_ds:: * _go32_my_ss:: * _go32_rmcb_stack_size:: * _go32_want_ctrl_break:: * _go32_was_ctrl_break_hit:: * gotoxy:: * gppconio_init:: * hasmntopt:: * highvideo:: * htonl:: * htons:: * hypot:: * inb:: * index:: * initstate:: * inp:: * inportb:: * inportl:: * inportsb:: * inportsl:: * inportsw:: * inportw:: * inpw:: * insline:: * insque:: * int386:: * int386x:: * int86:: * int86x:: * intdos:: * intdosx:: * intensevideo:: * _invent_inode:: * ioctl (DOS):: * ioctl (General description):: * ioctl (UNIX):: * _is_executable:: * _is_remote_drive:: * _is_remote_handle:: * isalnum:: * isalpha:: * isascii:: * isatty:: * iscntrl:: * isdigit:: * isgraph:: * islower:: * isprint:: * ispunct:: * isspace:: * isupper:: * isxdigit:: * itoa:: * kbhit:: * kill:: * labs:: * ldexp:: * ldiv:: * _lfn_gen_short_fname:: * _lfn_get_ftime:: * __libc_termios_init:: * libm:: * link:: * llabs:: * lldiv:: * load_npx:: * localeconv:: * localtime:: * lock:: * log:: * log10:: * log1p:: * log2:: * longjmp:: * lowvideo:: * lseek:: * malloc:: * matherr:: * mblen:: * mbstowcs:: * mbtowc:: * memccpy:: * memchr:: * memcmp:: * memcpy:: * memicmp:: * memmove:: * memset:: * mkdir:: * mkfifo:: * mknod:: * mkstemp:: * mktemp:: * mktime:: * modf:: * modfl:: * _mono_clear:: * _mono_printf:: * _mono_putc:: * movedata:: * movedatab:: * movedatal:: * movedataw:: * movetext:: * mprotect:: * _my_cs:: * _my_ds:: * _my_ss:: * nice:: * normvideo:: * nosound:: * ntohl:: * ntohs:: * open:: * _open:: * opendir:: * outb:: * outp:: * outportb:: * outportl:: * outportsb:: * outportsl:: * outportsw:: * outportw:: * outpw:: * pathconf:: * pause:: * pclose:: * perror:: * pipe:: * popen:: * pow:: * pow10:: * pow2:: * powi:: * _preserve_fncase:: * printf:: * psignal:: * _put_path:: * putc:: * putch:: * putchar:: * putenv:: * puts:: * puttext:: * putw:: * qsort:: * raise:: * rand:: * rand48:: * random:: * rawclock:: * read:: * _read:: * read_child:: * read_sel_addr:: * readdir:: * realloc:: * redir_cmdline_delete:: * redir_cmdline_parse:: * redir_debug_init:: * redir_to_child:: * redir_to_debugger:: * regcomp:: * regerror:: * regexec:: * regfree:: * remove:: * remque:: * _rename:: * rename:: * rewind:: * rewinddir:: * rindex:: * rmdir:: * run_child:: * save_npx:: * sbrk:: * scanf:: * Screen Variables:: * ScreenClear:: * ScreenCols:: * ScreenGetChar:: * ScreenGetCursor:: * ScreenMode:: * ScreenPutChar:: * ScreenPutString:: * ScreenRetrieve:: * ScreenRows:: * ScreenSetCursor:: * ScreenUpdate:: * ScreenUpdateLine:: * ScreenVisualBell:: * searchpath:: * seekdir:: * select:: * _set_screen_lines:: * setbuf:: * setbuffer:: * setcbrk:: * _setcursortype:: * setdate:: * setdisk:: * setenv:: * setftime:: * setgid:: * setgrent:: * setitimer:: * setjmp:: * setlinebuf:: * setlocale:: * setmntent:: * setmode:: * setpgid:: * setpwent:: * setrlimit:: * setsid:: * setstate:: * settime:: * settimeofday:: * setuid:: * setvbuf:: * sigaction:: * sigaddset:: * sigdelset:: * sigemptyset:: * sigfillset:: * sigismember:: * siglongjmp:: * signal:: * sigpending:: * sigprocmask:: * sigsetjmp:: * sin:: * sincos:: * sinh:: * sleep:: * sound:: * spawn*:: * sprintf:: * sqrt:: * srand:: * srandom:: * sscanf:: * stackavail:: * stat:: * statfs:: * _status87:: * _stklen:: * stpcpy:: * strcasecmp:: * strcat:: * strchr:: * strcmp:: * strcoll:: * strcpy:: * strcspn:: * strdup:: * strerror:: * strftime:: * stricmp:: * strlen:: * strlwr:: * strncasecmp:: * strncat:: * strncmp:: * strncpy:: * strnicmp:: * strpbrk:: * strrchr:: * strsep:: * strspn:: * strstr:: * strtod:: * strtok:: * strtol:: * _strtold:: * strtoll:: * strtoul:: * strtoull:: * strupr:: * strxfrm:: * swab:: * symlink:: * syms_init:: * syms_line2val:: * syms_listwild:: * syms_module:: * syms_name2val:: * syms_val2line:: * syms_val2name:: * sync:: * sys_errlist:: * sys_nerr:: * sysconf:: * system:: * tan:: * tanh:: * tcdrain:: * tcflow:: * tcflush:: * tcgetattr:: * tcgetpgrp:: * tcsendbreak:: * tcsetattr:: * tcsetpgrp:: * tell:: * telldir:: * tempnam:: * Termios functions:: * textattr:: * textbackground:: * textcolor:: * textmode:: * time:: * times:: * tmpfile:: * tmpnam:: * toascii:: * tolower:: * toupper:: * _truename:: * truncate:: * ttyname:: * tzset:: * tzsetwall:: * uclock:: * umask:: * uname:: * ungetc:: * ungetch:: * unlink:: * unlock:: * _use_lfn:: * usleep:: * utime:: * utimes:: * v2loadimage:: * varargs:: * vfork:: * vfprintf:: * vfscanf:: * vprintf:: * vscanf:: * vsprintf:: * vsscanf:: * wait:: * waitpid:: * wcstombs:: * wctomb:: * wherex:: * wherey:: * wild:: * window:: * write:: * _write:: * write_child:: * write_sel_addr:: * xfree:: * xmalloc:: * xrealloc:: File: libc.info, Node: _8087, Next: abort, Up: Alphabetical List _8087 ===== Syntax ------ #include <dos.h> extern int _8087; Description ----------- This variable is provided for compatibility with other DOS compilers. It contains `3' if a numeric coprocessor is installed, otherwise `0'. If the environment variable `387' is set to either `y' or `n', the value of `_8087' reflects the override (i.e., `_8087' is unconditionally assigned the value 3 if `387' is set to `y', 0 if it is set to `n'). Portability ----------- not ANSI, not POSIX File: libc.info, Node: abort, Next: abs, Prev: _8087, Up: Alphabetical List abort ===== Syntax ------ #include <stdlib.h> void abort(void); Description ----------- When you call `abort', the message "Abort!" is printed on stdout and the program is aborted by calling `raise (SIGABRT)' (*note SIGABRT: signal.). By default, this causes the CPU registers and the call frame stack dump to be printed, and the program then exits with an exit code of -1 (255). If the `SIGABRT' signal is caught by a handler that returns, the program exits with an exit code of 1. Return Value ------------ This function does not return. Portability ----------- ANSI, POSIX Example ------- if ((q = malloc(100)) == NULL) abort(); File: libc.info, Node: abs, Next: access, Prev: abort, Up: Alphabetical List abs === Syntax ------ #include <stdlib.h> int abs(int value); Return Value ------------ The absolute value of `value' is returned. Portability ----------- ANSI, POSIX Example ------- int sq = 7; sq = sq * abs(sq) + 1; File: libc.info, Node: access, Next: acos, Prev: abs, Up: Alphabetical List access ====== Syntax ------ #include <unistd.h> int access(const char *filename, int flags); Description ----------- This function determines what kind of access modes a given file allows. The parameter FLAGS is the logical `or' of one or more of the following flags: `R_OK' Request if the file is readable. Since all files are readable under MS-DOS, this access mode always exists. `W_OK' Request if the file is writable. `X_OK' Request if the file is executable. `F_OK' Request if the file exists. `D_OK' Request if the file is really a directory. Return Value ------------ Zero if the requested access mode is allowed, nonzero if not. Portability ----------- not ANSI, POSIX Example ------- if (access("file.ext", W_OK)) return ERROR_CANNOT_WRITE; open("file.ext", O_RDWR); File: libc.info, Node: acos, Next: acosh, Prev: access, Up: Alphabetical List acos ==== Syntax ------ #include <math.h> double acos(double x); Description ----------- This function returns the angle in the range `[0..Pi]' radians whose cosine is X. If the absolute value of X is greater than 1, a domain error occurs, and `errno' is set to `EDOM'. Return Value ------------ The arc cosine, in radians, of X. If the absolute value of X is greater than 1, the function returns a `NaN'. Portability ----------- ANSI, POSIX File: libc.info, Node: acosh, Next: addmntent, Prev: acos, Up: Alphabetical List acosh ===== Syntax ------ #include <math.h> double acosh(double x); Description ----------- This function returns the inverse hyperbolic cosine of X. Return Value ------------ The inverse hyperbolic cosine of X. If the value of X is less than 1, the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: addmntent, Next: alarm, Prev: acosh, Up: Alphabetical List addmntent ========= Syntax ------ #include <mntent.h> int addmntent(FILE *filep, const struct mntent *mnt); Description ----------- This function is a no-op for MS-DOS, but is provided to assist in Unix ports. *Note getmntent::. Return Value ------------ This function always returns nonzero to signify an error. Portability ----------- not ANSI, not POSIX File: libc.info, Node: alarm, Next: alloca, Prev: addmntent, Up: Alphabetical List alarm ===== Syntax ------ #include <unistd.h> unsigned alarm(unsigned seconds); Description ----------- This function causes the signal `SIGALRM' to be raised in SECONDS seconds. A value of zero for SECONDS cancels any pending alarm. If an alarm has previously been set, the new alarm delay will supercede the prior call. Note that signals in DJGPP are deferred when the program is inside a real-mode (e.g., DOS) call or isn't touching its data; see *Note signal::, for more details. A misfeature of Windows 9X prevents the timer tick interrupt from being delivered to programs that are in the background (i.e. don't have the focus), even though the program itself might continue to run, if you uncheck the `Background: Always suspend' property in the Property Sheets. Therefore, `alarm' will not work in background programs on Windows 9X. Return Value ------------ The number of seconds remaining on the timer (i.e. always SECONDS). Portability ----------- not ANSI, POSIX Example ------- signal(SIGALRM,my_alarm_routine); alarm(5); File: libc.info, Node: alloca, Next: asctime, Prev: alarm, Up: Alphabetical List alloca ====== Syntax ------ #include <stdlib.h> void *alloca(size_t _size) Description ----------- Allocate memory that will be automatically released when the current procedure exits. Note that, when compiling with gcc, alloca is a built-in function and not a library call. Return Value ------------ A pointer to the memory, else NULL. Portability ----------- not ANSI, not POSIX Example ------- q = alloca(strlen(x)+1); strcpy(q, x); File: libc.info, Node: asctime, Next: asin, Prev: alloca, Up: Alphabetical List asctime ======= Syntax ------ #include <time.h> char *asctime(const struct tm *tptr); Description ----------- This function returns an ASCII representation of the time represented by TPTR. The string returned is always 26 characters and has this format: Sun Jan 01 12:34:56 1993\n\0 The string pointed to is in a static buffer and will be overwritten with each call to asctime. The data should be copied if it needs to be preserved. The layout of the `struct tm' structure is like this: struct tm { int tm_sec; /* seconds after the minute [0-60] */ int tm_min; /* minutes after the hour [0-59] */ int tm_hour; /* hours since midnight [0-23] */ int tm_mday; /* day of the month [1-31] */ int tm_mon; /* months since January [0-11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday [0-6] */ int tm_yday; /* days since January 1 [0-365] */ int tm_isdst; /* Daylight Savings Time flag */ long tm_gmtoff; /* offset from GMT in seconds */ char * tm_zone; /* timezone abbreviation */ }; Return Value ------------ A pointer to the string. Portability ----------- ANSI, POSIX Example ------- time_t now; time(&now); printf("The current time is %s", asctime(localtime(&now))); File: libc.info, Node: asin, Next: asinh, Prev: asctime, Up: Alphabetical List asin ==== Syntax ------ #include <math.h> double asin(double x); Description ----------- This function returns the angle in the range `[-Pi/2..Pi/2]' whose sine is X. Return Value ------------ The inverse sine, in radians, of X. If the absolute value of X is greater than 1, the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: asinh, Next: assert, Prev: asin, Up: Alphabetical List asinh ===== Syntax ------ #include <math.h> double asinh(double x); Description ----------- This function returns the inverse hyperbolic sine of the argument X. Return Value ------------ The inverse hyperbolic sine of X. If the argument X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. If X is a positive or negative `Inf', the return value is equal to the value of X, and `errno' is left unchanged. Portability ----------- not ANSI, not POSIX File: libc.info, Node: assert, Next: atan, Prev: asinh, Up: Alphabetical List assert ====== Syntax ------ #define NDEBUG #include <assert.h> assert(expression); assertval(expression); Description ----------- These macros are used to assist in debugging. The source code includes references to assert and assertval, passing them expressions that should be true (or non-zero). When the expression equals zero, a diagnostic message is printed to stderr and the program aborts. If you define the macro `NDEBUG' before including `assert.h', then the macros expand to nothing to reduce code size after debugging is done. Return Value ------------ `assert' returns one if it passes, else it aborts. `assertval' returns the value of the expression if nonzero, else it aborts. Portability ----------- ANSI (see note 1), POSIX (see note 2) Notes: 1. `assert' is ANSI, `assertval' is not. 2. `assert' is Posix, `assertval' is not. Example ------- int strdup(char *s) { assert(s != 0); File: libc.info, Node: atan, Next: atan2, Prev: assert, Up: Alphabetical List atan ==== Syntax ------ #include <math.h> double atan(double x); Description ----------- This function computes the angle, in the range `[-Pi/2..Pi/2]' radians, whose tangent is X. Return Value ------------ The arc tangent, in radians, of X. If X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. If X is a positive or negative `Inf', the return value is equal to positive or negative `Pi/2', respectively, and `errno' is left unchanged. Portability ----------- ANSI, POSIX File: libc.info, Node: atan2, Next: atanh, Prev: atan, Up: Alphabetical List atan2 ===== Syntax ------ #include <math.h> double atan2(double y, double x); Description ----------- This function computes the angle, in the range `[-Pi..Pi]' radians, whose tangent is `Y/X'. In other words, it computes the angle, in radians, of the vector (X,Y) with respect to the `+x' axis, reckoning the counterclockwise direction as positive, and returning the value in the range `[-Pi, Pi]'. Return Value ------------ The arc tangent, in radians, of `Y/X'. `Pi' is returned if X is negative and Y is a negative zero, `-0.0'. `-Pi' is returned, if X is negative, and Y is a positive zero, `+0.0'. If either X or Y is infinite, `atan2' returns, respectively, `Pi' with the sign of Y or zero, and `errno' is left unchanged. However, if *both* arguments are infinite, the return value is `NaN' and `errno' is set to `EDOM'. A `NaN' is returned, and `errno' is set to `EDOM', if either X and Y are both zero, or if either one of the arguments is a `NaN'. Portability ----------- ANSI, POSIX File: libc.info, Node: atanh, Next: atexit, Prev: atan2, Up: Alphabetical List atanh ===== Syntax ------ #include <math.h> double atanh(double x); Description ----------- This function computes the inverse hyperbolic tangent of X. Return Value ------------ The inverse hyperbolic tangent of X. If the the value of X is plus or minus 1, the return value is an `Inf' with the same sign as the argument X, and `errno' is set to `ERANGE'. If the absolute value of X is greater than 1, the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: atexit, Next: atof, Prev: atanh, Up: Alphabetical List atexit ====== Syntax ------ #include <stdlib.h> int atexit(void (*func)(void)); Description ----------- This function places the specified function FUNC on a list of functions to be called when `exit' is called. These functions are called as if a last-in-first-out queue is used, that is, the last function registered with `atexit' will be the first function called by `exit'. At least 32 functions can be registered this way. Return Value ------------ Zero on success, non-zero on error. Portability ----------- ANSI, POSIX Example ------- void exit_func() { remove("file.tmp"); } ... atexit(exit_func); ... File: libc.info, Node: atof, Next: atoi, Prev: atexit, Up: Alphabetical List atof ==== Syntax ------ #include <stdlib.h> double atof(const char *string); Description ----------- Convert as much of the string as possible to an equivalent double precision real number. This function is almost like `strtod(string, NULL)' (*note strtod::.). Return Value ------------ The equivalent value, or zero if the string does not represent a number. Portability ----------- ANSI, POSIX Example ------- main(int argc, char **argv) { double d = atof(argv[1]); ... File: libc.info, Node: atoi, Next: atol, Prev: atof, Up: Alphabetical List atoi ==== Syntax ------ #include <stdlib.h> int atoi(const char *string); Description ----------- Convert as much of the string as possible to an equivalent integer value. This function is almost like `(int)strtol(string, NULL, 10)' (*note strtol::.). Return Value ------------ The equivalent value, or zero if the string does not represent a number. Portability ----------- ANSI, POSIX Example ------- main(int argc, char **argv) { int i = atoi(argv[1]); ... File: libc.info, Node: atol, Next: _atold, Prev: atoi, Up: Alphabetical List atol ==== Syntax ------ #include <stdlib.h> long atol(const char *string); Description ----------- Convert as much of the string as possible to an equivalent long integer value. This function is almost like `strtol(string, NULL, 10)' (*note strtol::.). Return Value ------------ The equivalent value, or zero if the string does not represent a number. Portability ----------- ANSI, POSIX Example ------- main(int argc, char **argv) { long l = atol(argv[1]); ... File: libc.info, Node: _atold, Next: basename, Prev: atol, Up: Alphabetical List _atold ====== Syntax ------ #include <stdlib.h> long double _atold(const char *string); Description ----------- Convert as much of the string as possible to an equivalent long double precision real number. This function is almost like `_strtold(string, NULL)' (*note _strtold::.). Return Value ------------ The equivalent value, or zero if the string does not represent a number. Portability ----------- not ANSI, not POSIX Example ------- main(int argc, char **argv) { long double d = _atold(argv[1]); ... File: libc.info, Node: basename, Next: bcmp, Prev: _atold, Up: Alphabetical List basename ======== Syntax ------ #include <unistd.h> char * basename (const char *fname); Description ----------- This function returns the "basename" of the file, which is the last part of its full name given by FNAME, with the drive letter and leading directories stripped off. For example, the basename of `c:/foo/bar/file.ext' is `file.ext', and the basename of `a:foo' is `foo'. Trailing slashes and backslashes are significant: the basename of `c:/foo/bar/' is an empty string after the rightmost slash. This function treats both forward- and backslashes like directory separators, so it can handle file names with mixed styles of slashes. Return Value ------------ A pointer into the original file name where the basename starts. Note that this is *not* a new buffer allocated with `malloc'. If FNAME is a NULL pointer, the function will return a NULL pointer. Portability ----------- not ANSI, not POSIX Example ------- if (strcmp (basename (file_name), "gcc.exe") == 0) printf ("The file %s is the GNU C/C++ compiler\n", file_name); File: libc.info, Node: bcmp, Next: bcopy, Prev: basename, Up: Alphabetical List bcmp ==== Syntax ------ #include <string.h> int bcmp(const void *ptr1, const void *ptr2, int length); Description ----------- Compare memory pointed to by PTR1 and PTR2 for at most LENGTH bytes. Return Value ------------ The number of bytes remaining when the first mismatch occurred, or zero if all bytes were equal. Portability ----------- not ANSI, not POSIX Example ------- void f(char *s1, char *s2) { int l = bcmp(s1, s2, strlen(s1)); printf("Difference: %s, %s\n", s1+strlen(s1)-l, s2+strlen(s1)-l); } File: libc.info, Node: bcopy, Next: bdos, Prev: bcmp, Up: Alphabetical List bcopy ===== Syntax ------ #include <string.h> void bcopy(const void *source, void *dest, int length); Description ----------- Copy LENGTH bytes from SOURCE to DEST. Overlapping regions are handled properly, although this behavior is not portable. Return Value ------------ No value is returned. Portability ----------- not ANSI, not POSIX Example ------- struct s a, b; bcopy(a, b, sizeof(struct s)); File: libc.info, Node: bdos, Next: bdosptr, Prev: bcopy, Up: Alphabetical List bdos ==== Syntax ------ #include <dos.h> int bdos(int func, unsigned dx, unsigned al); Description ----------- Calls function FUNC of the software interrupt 0x21, passing it AL as the subfunction and (the lower 16 bit of) DX in the `DX' register. This function will only work for a subset of DOS functions which require no arguments at all, or take non-pointer arguments in the `AL' and `DX' registers only. For functions which require a pointer in the `DX' register, use `bdosptr' (*note bdosptr::.). Return Value ------------ Whatever the called function returns in the AX register. Portability ----------- not ANSI, not POSIX Example ------- /* read a character */ int ch = bdos(1, 0, 0) & 0xff; File: libc.info, Node: bdosptr, Next: _bios_disk, Prev: bdos, Up: Alphabetical List bdosptr ======= Syntax ------ #include <dos.h> int bdosptr(int func, void *ptr, unsigned al); Description ----------- Calls function FUNC of the software interrupt 0x21, passing it AL as the subfunction and a pointer to a copy of the buffer contents whose address is in PTR through the `DX' register. This function will only work for a subset of DOS which require an argument in the `AL' register and a pointer in `DX' register. For functions which require non-pointer arguments in the `DX' register, use `bdos' (*note bdos::.). To make the contents of PTR available to DOS, `bdosptr' copies it to the transfer buffer located in the low (below 1 Meg mark) memory. Currently, some of the functions which take a pointer to a buffer in `DX' are *NOT* supported (notably, most of the FCB-based functions). *Note int86::, for the list of supported functions. Return Value ------------ Whatever the called function returns in the AX register. Portability ----------- not ANSI, not POSIX Example ------- /* print a string */ bdosptr(9, "Hello, there$", 0); File: libc.info, Node: _bios_disk, Next: _bios_equiplist, Prev: bdosptr, Up: Alphabetical List _bios_disk ========== Syntax ------ #include <bios.h> unsigned _bios_disk(unsigned cmd, struct diskinfo_t *di) Description ----------- This function interfaces with the BIOS disk sevice (interrupt 0x13). The parameter CMD select the corresponding disk service and the structure DI holds the disk parameters. struct diskinfo_t { unsigned drive; /* Drive number. */ unsigned head; /* Head number. */ unsigned track; /* Track number. */ unsigned sector; /* Sector number. */ unsigned nsectors; /* Number of sectors to read/write/verify. */ void *buffer; /* Buffer for reading/writing/verifying. */ } The following services are available based on value of CMD: `_DISK_RESET' Forces the disk controller to do a hard reset, preparing for floppy-disk I/O. This is useful after an error occurs in another operation, such as a read. If this service is specified, the DI argument is ignored. Status is returned in the 8 high-order bits (AH) of the return value. If there is an error, the high-order byte will contain a set of status flags, as defined below under Return Value. `_DISK_STATUS' Obtains the status of the last disk operation. If this service is specified, the <diskinfo> argument is ignored. Status is returned in the 8 low-order bits (AL) of the return value. If there is an error, the low-order byte (AL) will contain a set of status flags, as defined below under Return Value. `_DISK_READ' Reads one or more disk sectors into memory. This service uses all fields of the structure pointed to by DISKINFO. If no error occurs, the function returns 0 in the high-order byte and the number of sectors read in the low-order byte. If there is an error, the high-order byte (AH) will contain a set of status flags, as defined below under Return Value. `_DISK_WRITE' Writes data from memory to one or more disk sectors. This service uses all fields of the structure pointed to by <diskinfo>. If no error occurs, the function returns 0 in the high-order byte (AH) and the number of sectors written in the low-order byte (AL). If there is an error, the high-order byte will contain a set of status flags, as defined below under Return Value. `_DISK_FORMAT' Formats the track specified by DISKINFO. The HEAD and TRACK fields indicate the track to format. Only one track can be formatted in a single call. The BUFFER field points to a set of sector markers. The format of the markers depends on the type of disk drive (see a technical reference to the PC BIOS to determine the marker format). The high-order byte (AH) of the return value contains the status of the call; 0 equals success. If there is an error, the high-order byte will contain a set of status flags, as defined below under Return Value. `_DISK_VERIFY' Checks the disk to be sure the specified sectors exist and can be read. It also runs a CRC (cyclic redundancy check) test. This service uses all fields (except BUFFER) of the structure pointed to by DISKINFO. If no error occurs, the function returns 0 in the high-order byte (AH) and the number of sectors compared in the low-order byte (AL), as defined below under Return Value. Return Value ------------ Return value of AX register. The meaning of high-order byte (AH): 0x00 No error 0x01 Invalid request or a bad command 0x02 Address mark not found 0x03 Disk write protected 0x04 Sector not found 0x05 Reset failed 0x06 Floppy disk removed 0x07 Drive parameter activity failed 0x08 Direct Memory Access (DMA) overrun 0x09 DMA crossed 64K boundary 0x0A Bad sector flag detected 0x0B Bad track flag detected 0x0C Media type not found 0x0D Invalid number of sectors on format 0x0E Control data access mark detected 0x0F DMA arbitration level out of range 0x10 Data read (CRC or ECC) error 0x11 Corrected data read (ECC) error 0x20 Controller failure 0x40 Seek error 0x80 Disk timed out or failed to respond 0xAA Drive not ready 0xBB Undefined error 0xCC Write fault on drive 0xE0 Status error 0xFF Sense operation failed Portability ----------- not ANSI, not POSIX Example ------- char record_buffer[512]; struct diskinfo_t di; di.drive = 0x80; di.head = 0; di.track = 0; di.sector = 0; di.nsectors = 1; di.buffer = &record_buffer; if ( _bios_disk(_DISK_READ, &di) ) puts("Disk error."); File: libc.info, Node: _bios_equiplist, Next: _bios_keybrd, Prev: _bios_disk, Up: Alphabetical List _bios_equiplist =============== Syntax ------ #include <bios.h> unsigned _bios_equiplist(void) Description ----------- This function returns the equipment word from BIOS request 0x11. The bits correspond to the following values: Bits Meaning 0 True (1) if disk drive(s) installed 1 True (1) if math coprocessor installed 2-3 System RAM in 16K blocks (16-64K) 4-5 Initial video mode: 00 = Reserved 01 = 40 x 25 color 10 = 80 x 25 color 11 = 80 x 25 monochrome 6-7 Number of floppy-disk drives installed (00 = 1, 01 = 2, etc.) 8 False (0) if and only if a Direct Memory Access (DMA) chip is installed 9-11 Number of RS232 serial ports installed 12 True (1) if and only if a game adapter is installed 13 True (1) if and only if an internal modem is installed 14-15 Number of printers installed Return Value ------------ The equipment word. Portability ----------- not ANSI, not POSIX Example ------- if ( _bios_equiplist() & 0xc000 ) do_printing(); File: libc.info, Node: _bios_keybrd, Next: _bios_memsize, Prev: _bios_equiplist, Up: Alphabetical List _bios_keybrd ============ Syntax ------ #include <bios.h> unsigned _bios_keybrd(unsigned cmd); Description ----------- The _bios_keybrd routine uses INT 0x16 to access the keyboard services. The CMD argument can be any of the following manifest constants: `_KEYBRD_READ' Read the next key pressed `_NKEYBRD_READ' Read the next extended key pressed `_KEYBRD_READY' Check if the next key in the keyboard buffer `_NKEYBRD_READY' Check if the next extended key in the keyboard buffer `_KEYBRD_SHIFTSTATUS' Read keyboard shift state (0x0040:0x0017 byte): 7654 3210 Meaning ---- ---X Right SHIFT is pressed ---- --X- Left SHIFT is pressed ---- -X-- CTRL is pressed ---- X--- ALT is pressed ---X ---- Scroll Lock locked --X- ---- Num Lock locked -X-- ---- Caps Lock locked X--- ---- Insert locked `_NKEYBRD_SHIFTSTATUS' Read keyboard shift and extended shift state (0x0040:0x0017 word): FEDC BA98 7654 3210 Meaning ---- ---- ---- ---X Right SHIFT is pressed ---- ---- ---- --X- Left SHIFT is pressed ---- ---- ---- -X-- CTRL is pressed ---- ---- ---- X--- ALT is pressed ---- ---- ---X ---- Scroll Lock locked ---- ---- --X- ---- Num Lock locked ---- ---- -X-- ---- Caps Lock locked ---- ---- X--- ---- Insert locked ---- ---X ---- ---- Left CTRL is pressed ---- --X- ---- ---- Left ALT is pressed ---- -X-- ---- ---- Right CTRL is pressed ---- X--- ---- ---- Right ALT is pressed ---X ---- ---- ---- Scroll Lock is pressed --X- ---- ---- ---- Num Lock is pressed -X-- ---- ---- ---- Caps Lock is pressed X--- ---- ---- ---- SysReq is pressed Return Value With the ???_READ and ???_SHIFTSTATUS arguments, the _bios_keybrd function returns the contents of the AX register after the BIOS call. With the ???_READY argument, _bios_keybrd returns 0 if there is no key. If there is a key, _bios_keybrd returns the key waiting to be read (that is, the same value as _KEYBRD_READ). With the ???_READ and ???_READY arguments, the _bios_keybrd function returns -1 if CTRL+BREAK has been pressed and is the next keystroke to be read. Portability ----------- not ANSI, not POSIX Example ------- while( !_bios_keybrd(_KEYBRD_READY) ) try_to_do_something(); File: libc.info, Node: _bios_memsize, Next: _bios_printer, Prev: _bios_keybrd, Up: Alphabetical List _bios_memsize ============= Syntax ------ #include <bios.h> unsigned _bios_memsize(void); Description ----------- This function returns the amount of system memory in 1K blocks (up to 640K). Return Value ------------ Size of memory (in K). Portability ----------- not ANSI, not POSIX Example ------- printf("This system has %d bytes of memory\n", _bios_memsize() * 1024); File: libc.info, Node: _bios_printer, Next: _bios_serialcom, Prev: _bios_memsize, Up: Alphabetical List _bios_printer ============= Syntax ------ #include <bios.h> unsigned _bios_printer(unsigned cmd, unsigned printer, unsigned data); Description ----------- The _bios_printer routine uses INT 0x17 to perform printer output services for parallel printers. The PRINTER argument specifies the affected printer, where 0 is LPT1, 1 is LPT2, and so on. The CMD argument can be any of the following manifest constants: `_PRINTER_INIT' `Reset and initialize the specified printer port' `_PRINTER_STATUS' Return the status of the specified printer port `_PRINTER_WRITE' Print the DATA argument to the specified printer port Return Value ------------ The _bios_printer function returns the value in the AX register after the BIOS interrupt. The high-order byte (AH) of the return value indicates the printer status after the operation, as defined below: Bit Meaning if True 0 Printer timed out 1 Not used 2 Not used 3 I/O error 4 Printer selected 5 Out of paper 6 Acknowledge 7 Printer not busy Portability ----------- not ANSI, not POSIX Example ------- while (*c) _bios_printer(_PRINTER_WRITE, *c++, 0); File: libc.info, Node: _bios_serialcom, Next: _bios_timeofday, Prev: _bios_printer, Up: Alphabetical List _bios_serialcom =============== Syntax ------ #include <bios.h> unsigned _bios_serialcom(unsigned cmd, unsingned serialport, unsigned data); Description ----------- The _bios_serialcom routine uses INT 0x14 to provide serial communications services. The SERIALPORT argument is set to 0 for COM1, to 1 for COM2, and so on. The CMD argument can be set to one of the following manifest constants: `_COM_INIT' Initialize com port (DATA is the settings) `_COM_RECEIVE' Read a byte from port `_COM_SEND' Write a byte to port `_COM_STATUS' Get the port status The DATA argument is ignored if CMD is set to _COM_RECEIVE or _COM_STATUS. The DATA argument for _COM_INIT is created by combining one or more of the following constants (with the OR operator): _COM_CHR7 7 bits/character _COM_CHR8 8 bits/character _COM_STOP1 1 stop bit _COM_STOP2 2 stop bits _COM_NOPARITY no parity _COM_EVENPARITY even parity _COM_ODDPARITY odd parity _COM_110 110 baud _COM_150 150 baud _COM_300 300 baud _COM_600 600 baud _COM_1200 1200 baud _COM_2400 2400 baud _COM_4800 4800 baud _COM_9600 9600 baud The default value of DATA is 1 stop bit, no parity, and 110 baud. Return Value ------------ The function returns a 16-bit integer whose high-order byte contains status bits. The meaning of the low-order byte varies, depending on the CMD value. The high-order bits are as follows: Bit Meaning if Set 15 Timed out 14 Transmission-shift register empty 13 Transmission-hold register empty 12 Break detected 11 Framing error 10 Parity error 9 Overrun error 8 Data ready When service is _COM_SEND, bit 15 is set if data cannot be sent. When service is _COM_RECEIVE, the byte read is returned in the low-order bits if the call is successful. If an error occurs, any of the bits 9, 10, 11, or 15 is set. When service is _COM_INIT or _COM_STATUS, the low-order bits are defined as follows: Bit Meaning if Set 7 Receive-line signal detected 6 Ring indicator 5 Data-set-ready 4 Clear-to-send 3 Change in receive-line signal detected 2 Trailing-edge ring indicator 1 Change in data-set-ready status 0 Change in clear-to-send status Portability ----------- not ANSI, not POSIX Example ------- /* 9600 baud, no parity, one stop, 8 bits */ _bios_serialcom(_COM_INIT, 0, _COM_9600|_COM_NOPARITY|_COM_STOP1|_COM_CHR8); for(i=0; buf[i]; i++) _bios_serialcom(_COM_SEND, 0, buf[i]); File: libc.info, Node: _bios_timeofday, Next: bioscom, Prev: _bios_serialcom, Up: Alphabetical List _bios_timeofday =============== Syntax ------ #include <bios.h> unsigned _bios_timeofday(unsigned cmd, unsigned long *timeval); Description ----------- The _bios_timeofday routine uses INT 0x1A to get or set the clock count (which is the number of 18.2 Hz ticks since midnight). The CMD argument can be either the _TIME_GETCLOCK or _TIME_SETCLOCK manifest constant. Return Value ------------ If the argument is _TIME_GETCLOCK, the routine returns a nonzero value if midnight was passed since last read, or zero if midnight was not passed. If the argument is _TIME_SETCLOCK, the return value is undefined. Portability ----------- not ANSI, not POSIX Example ------- unsigned hour, min, sec, hsec; unsigned long ticks; ... ticks = (unsigned long)(hour * 65543.33) + (min * 1092.38) + (sec * 18.21) + (hsec * 0.182); _bios_timeofday(_TIME_SETCLOCK, &ticks); File: libc.info, Node: bioscom, Next: biosdisk, Prev: _bios_timeofday, Up: Alphabetical List bioscom ======= Syntax ------ #include <bios.h> int bioscom(int cmd, char data, int port); Description ----------- This function accesses the BIOS interrupt 0x14 function, serial communication services. `port' should be the COM port (0=COM1, 1=COM2, etc). The valid values of cmd are: 0 - initialize com port (DATA is the settings) 1 - write byte to port 2 - read byte from port (DATA is ignored) 3 - get port status For initialization, the byte is made up of the following bits: 0000 0000 7654 3210 Meaning ---- --10 7 bits/character ---- --11 8 bits/character ---- -0-- 1 stop bit ---- -1-- 2 stop bits ---X 0--- no parity ---0 1--- odd parity ---1 1--- even parity 000- ---- 110 baud 001- ---- 150 baud 010- ---- 300 baud 011- ---- 600 baud 100- ---- 1200 baud 101- ---- 2400 baud 110- ---- 4800 baud 111- ---- 9600 baud For writing a character out to the port, the return value's lower 8 bits contain the same byte as passed as the DATA argument. For reading a character from the port, the value of DATA is ignored, and the lower 8 bits of the return value contain the byte read. Also, the "timeout" bit in the upper 8 bits is used as an error indicator in this case (0=success, 1=error). If it indicates an error, you should call the "get port status" variant to get the detailed error bits. Return Value ------------ The return value is a sequence of bits that indicate the port status and, for cmd=0 and 3, the modem status. For read/write operations, the lower eight bits are the character read. 1111 1100 0000 0000 5432 1098 7654 3210 Meaning ---- ---- ---- ---1 CTS change ---- ---- ---- --1- DSR change ---- ---- ---- -1-- ring change ---- ---- ---- 1--- carrier detect change ---- ---- ---1 ---- CTS present ---- ---- --1- ---- DSR present ---- ---- -1-- ---- ring present ---- ---- 1--- ---- carrier detect ---- ---1 ---- ---- data ready ---- --1- ---- ---- overrun error ---- -1-- ---- ---- parity error ---- 1--- ---- ---- framing error ---1 ---- ---- ---- break detected --1- ---- ---- ---- transmit holding register empty -1-- ---- ---- ---- transmit shift register empty 1--- ---- ---- ---- time out (=1 if error present for cmd=1,2) Portability ----------- not ANSI, not POSIX Example ------- bioscom(0, 0xe3, 0); /* 9600 baud, no parity, one stop, 8 bits */ for (i=0; buf[i]; i++) bioscom(1, buf[i], 0); File: libc.info, Node: biosdisk, Next: biosequip, Prev: bioscom, Up: Alphabetical List biosdisk ======== Syntax ------ #include <bios.h> int biosdisk(int cmd, int drive, int head, int track, int sector, int nsects, void *buffer); Description ----------- This function interfaces with the BIOS disk service (interrupt 0x13). Please refer to a BIOS reference manual for detailed information about the parameters of this call. The function assumes a sector size of 512 bytes. The following functions of Int 13h are currently supported: 0 - reset disk subsystem 1 - get status of last operation (see *Note _bios_disk::, for possible values) 2 - read one or more sectors 3 - write one or more sectors 5 - format a track 6 - format a cylinder and set bad sector flag 7 - format drive from specified cylinder 8 - get drive parameters 9 - initialize drive parameters 10 - read long sectors 11 - write long sectors 12 - seek to cylinder 13 - alternate fixed disk reset 14 - read sector buffer 15 - write sector buffer 16 - test for drive ready 17 - recalibrate drive 18 - controller RAM diagnostic 19 - controller drive diagnostic 20 - controller internal diagnostic 21 - get DASD type 22 - read disk change line status 23 - set DASD type (pass DASD code in NSECTS) 24 - set media type for format The first request with more sectors than will fit in the transfer buffer will cause a DOS buffer to be allocated. This buffer is automatically freed when your application exits. Requests for more sectors than 18 sectors (9K) will fail. Function 8 returns values in BUFFER as follows: byte 0 = sectors per track (bits 0..5), top two bits of cylinder (in bits 6..7) byte 1 = cylinders (bits 0..7) byte 2 = number of drives byte 3 = number of heads Return Value ------------ The value of AH returned by the BIOS. See *Note _bios_disk::, for a detailed list of possible status and error codes. Portability ----------- not ANSI, not POSIX Example ------- char buffer[512]; if (biosdisk(2, 0x80, 0, 0, 0, 1, buffer)) error("disk"); File: libc.info, Node: biosequip, Next: bioskey, Prev: biosdisk, Up: Alphabetical List biosequip ========= Syntax ------ #include <bios.h> int biosequip(void); Description ----------- This function returns the equipment word from BIOS request 0x11. The bits correspond to the following values: 1111 1100 0000 0000 5432 1098 7654 3210 Meaning ---- ---- ---- ---X 1 = disk drive(s) installed ---- ---- ---- --X- 1 = math coprocessor installed ---- ---- ---- XX-- System memory 00=16k 01=32k 10=48k 11=64k (non PS/2) ---- ---- ---- -X-- 1 = pointing device installed (PS/2) ---- ---- ---- X--- not used on PS/2 ---- ---- --XX ---- initial video mode: 01=CO40 10=CO80 11=MONO ---- ---- XX-- ---- disk drives 00=1 01=2 10=3 11=4 (zero if bit 1=0) ---- ---X ---- ---- 1 = no DMA available ---- XXX- ---- ---- number of serial ports installed (000=0 001=1 etc) ---X ---- ---- ---- 1 = game port adapter installed --X- ---- ---- ---- 1 = internal modem installed (PS/2) --X- ---- ---- ---- 1 = serial printer attached (non PS/2) XX-- ---- ---- ---- number of printers installed (00=0 01=1 10=2 11=3) Return Value ------------ The equipment word. Portability ----------- not ANSI, not POSIX Example ------- if (biosequip() & 0xc000) do_printing(); File: libc.info, Node: bioskey, Next: biosmemory, Prev: biosequip, Up: Alphabetical List bioskey ======= Syntax ------ #include <bios.h> int bioskey(int command) Description ----------- This function issues the BIOS keyboard interrupt 16h with COMMAND in the AH register, and returns the results of that call. The argument COMMAND can accept the following values: COMMAND = 0 Returns the next key pressed. The value returned is a combination of the key's scan code in the high 8 bits and its ASCII code in the low 8 bits. COMMAND = 1 Checks the keyboard, returns zero if no key pressed, else the key. Does not dequeue the key from the keyboard buffer. The value returned when a key was pressed is a combination of the key's scan code in the high 8 bits and its ASCII code in the low 8 bits. If the `Ctrl-<BREAK>' key was pressed, returns -1. COMMAND = 2 Returns the shift state: 7654 3210 Meaning ---- ---X Right shift key down ---- --X- Left shift key down ---- -X-- Ctrl key down ---- X--- Alt key down ---X ---- Scroll lock on --X- ---- Num lock on -X-- ---- Caps lock on X--- ---- Insert on COMMAND = 10 Returns the next extended key pressed. This works like the case of COMMAND = 0, but it recognizes additional keys from the AT-style extended 101-key keyboard, like the second <Alt> key and <F12>. If a key was pressed, returns the scan code and ASCII code packed in same way as for COMMAND = 0. Almost every PC nowadays has an extended 101-key keyboard. COMMAND = 11 Like the case of COMMAND = 1, but recognizes the additional keys of the extended keyboard. COMMAND = 12 Returns the two status bytes of the enhanced keyboard, packed in the low 16 bits of the return value. The individual bits of the return value are defined in the following table: FEDC BA98 7654 3210 Meaning ---- ---- ---- ---X Right SHIFT is pressed ---- ---- ---- --X- Left SHIFT is pressed ---- ---- ---- -X-- CTRL is pressed ---- ---- ---- X--- ALT is pressed ---- ---- ---X ---- Scroll Lock locked ---- ---- --X- ---- Num Lock locked ---- ---- -X-- ---- Caps Lock locked ---- ---- X--- ---- Insert locked ---- ---X ---- ---- Left CTRL is pressed ---- --X- ---- ---- Left ALT is pressed ---- -X-- ---- ---- Right CTRL is pressed ---- X--- ---- ---- Right ALT is pressed ---X ---- ---- ---- Scroll Lock is pressed --X- ---- ---- ---- Num Lock is pressed -X-- ---- ---- ---- Caps Lock is pressed X--- ---- ---- ---- SysReq is pressed Return Value ------------ Depends on COMMAND. Portability ----------- not ANSI, not POSIX Example ------- while (!bioskey(1)) do_stuff(); File: libc.info, Node: biosmemory, Next: biosprint, Prev: bioskey, Up: Alphabetical List biosmemory ========== Syntax ------ #include <bios.h> unsigned biosmemory(void); Description ----------- This function returns the amount of system memory in 1k blocks. Note that this function doesn't know about extended memory above the 640K mark, so it will report 640K at most. This is a limitation of the BIOS. Return Value ------------ Bytes of memory / 1024. Portability ----------- not ANSI, not POSIX Example ------- printf("This system has %d bytes of memory\n", biosmemory()*1024); File: libc.info, Node: biosprint, Next: biostime, Prev: biosmemory, Up: Alphabetical List biosprint ========= Syntax ------ #include <bios.h> int biosprint(int cmd, int byte, int port) Description ----------- COMMAND = 0 `byte' is sent to parallel port PORT. COMMAND = 1 Parallel port PORT is reset and initialized. COMMAND = 2 The status of parallel port PORT is returned. 7654 3210 Meaning ---- ---X Timeout ---- -XX- Unused ---- X--- I/O Error ---X ---- Selected --X- ---- Out of paper -X-- ---- Acknowledged X--- ---- Idle Return Value ------------ The printer status. Portability ----------- not ANSI, not POSIX Example ------- while (*c) biosprint(0, *c++, 0); File: libc.info, Node: biostime, Next: blinkvideo, Prev: biosprint, Up: Alphabetical List biostime ======== Syntax ------ #include <bios.h> long biostime(int cmd, long newtime); Description ----------- This function reads (CMD=0) or sets (CMD=1) the internal tick counter, which is the number of 18.2 Hz ticks since midnight. Return Value ------------ When reading, the number of ticks since midnight. Portability ----------- not ANSI, not POSIX Example ------- long ticks = biostime(0, 0); File: libc.info, Node: blinkvideo, Next: brk, Prev: biostime, Up: Alphabetical List blinkvideo ========== Syntax ------ #include <conio.h> void blinkvideo(void); Description ----------- Bit 7 (`MSB') of the character attribute byte has two possible effects on EGA and VGA displays: it can either make the character blink or change the background color to bright (thus allowing for 16 background colors as opposed to the usual 8). This function sets that bit to display blinking characters. After a call to this function, every character written to the screen with bit 7 of the attribute byte set, will blink. The companion function `intensevideo' (*note intensevideo::.) has the opposite effect. Note that there is no BIOS function to get the current status of this bit, but bit 5 of the byte at `0040h:0065h' in the BIOS area indicates the current state: if it's 1 (the default), blinking characters will be displayed. Portability ----------- not ANSI, not POSIX File: libc.info, Node: brk, Next: bsearch, Prev: blinkvideo, Up: Alphabetical List brk === Syntax ------ #include <unistd.h> int brk(void *ptr); Description ----------- This function changes the *break* for the program. This is the first address that, if referenced, will cause a fault to occur. The program asks for more memory by specifying larger values for PTR. Normally, this is done transparently through the `malloc' function. Return Value ------------ Zero if the break was changed, -1 if not. ERRNO is set to the error. Portability ----------- not ANSI, not POSIX Example ------- if (brk(old_brk+1000)) printf("no memory\n"); File: libc.info, Node: bsearch, Next: bzero, Prev: brk, Up: Alphabetical List bsearch ======= Syntax ------ #include <stdlib.h> void *bsearch (const void *key, const void *base, size_t num, size_t size, int (*ptf)(const void *ckey, const void *celem)); Description ----------- Given an array of values, perform a binary search on the values looking for value that "matches" the given key. A match is determined by calling the provided function PTF and passing it the key as CKEY and a pointer to one of the elements of the array as CELEM. This function must return a negative number if the key is closer than the element to the beginning of the array, positive if it is closer to the end, and zero if the element matches the key. The array begins at address BASE and contains NUM elements, each of size SIZE. Return Value ------------ Returns a pointer to the element that matches the key, else NULL. Portability ----------- ANSI, POSIX Example ------- typedef struct { int a, b; } q; int compare(void *key, void *elem) { return *(int *)key - ((q *)elem)->a; } q qlist[100]; ... q *match = bsearch(4, qlist, 100, sizeof(q), compare); printf("4->%d=n", match->b); ... File: libc.info, Node: bzero, Next: calloc, Prev: bsearch, Up: Alphabetical List bzero ===== Syntax ------ #include <string.h> void bzero(void *pointer, int length); Description ----------- The data at POINTER is filled with LENGTH zeros. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- char foo[100]; bzero(foo,100); File: libc.info, Node: calloc, Next: cbrt, Prev: bzero, Up: Alphabetical List calloc ====== Syntax ------ #include <stdlib.h> void *calloc(size_t num_elements, size_t size); Description ----------- This function allocates enough memory for NUM_ELEMENTS objects of size SIZE. The memory returned is initialized to all zeros. The pointer returned should later be passed to free (*note free::.) so that the memory can be returned to the heap. You may use cfree (*note xfree::.) to free the pointer also; it just calls free. Return Value ------------ A pointer to the memory, or `NULL' if no more memory is available. Portability ----------- ANSI, POSIX Example ------- Complex *x = calloc(12, sizeof(Complex)); cfree(x); File: libc.info, Node: cbrt, Next: ceil, Prev: calloc, Up: Alphabetical List cbrt ==== Syntax ------ #include <math.h> double cbrt(double x); Description ----------- This function computes the cube root of X. It is faster and more accurate to call `cbrt(X)' than to call `pow(X, 1./3.)'. Return Value ------------ The cube root of X. If the value of X is `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Infinite arguments are returned unchanged, without setting `errno'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: ceil, Next: cfgetispeed, Prev: cbrt, Up: Alphabetical List ceil ==== Syntax ------ #include <math.h> double ceil(double x); Description ----------- This function computes the smallest integer greater than or equal to X. Return Value ------------ The smallest integer value greater than or equal to X. Portability ----------- ANSI, POSIX File: libc.info, Node: cfgetispeed, Next: cfgetospeed, Prev: ceil, Up: Alphabetical List cfgetispeed =========== Syntax ------ #include <termios.h> speed_t cfgetispeed (const struct termios *termiosp); Description ----------- This function gets the input line speed stored in the structure TERMIOSP. *Note Termios functions::, for more details about this structure and the baudrate values it supports. Note that the termios emulation handles console only, and that the input baudrate value is ignored by this implementation. Return Value ------------ The input line speed on success, (speed_t) -1 for error. Portability ----------- not ANSI, POSIX File: libc.info, Node: cfgetospeed, Next: cfmakeraw, Prev: cfgetispeed, Up: Alphabetical List cfgetospeed =========== Syntax ------ #include <termios.h> speed_t cfgetospeed (const struct termios *termiosp); Description ----------- This function gets the output line speed stored in the structure TERMIOSP. *Note Termios functions::, for more details about this structure and the baudrate values it supports. Note that the termios emulation handles console only, and that the baudrate value has no effect in this implementation. Return Value ------------ The output line speed on success, (speed_t) -1 for error. Portability ----------- not ANSI, POSIX File: libc.info, Node: cfmakeraw, Next: cfree, Prev: cfgetospeed, Up: Alphabetical List cfmakeraw ========= Syntax ------ #include <termios.h> void cfmakeraw (struct termios *termiosp); Description ----------- This function sets the structure specified by TERMIOSP for raw mode. It is provided for compatibility only. Note that the termios emulation handles console only. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: cfree, Next: cfsetispeed, Prev: cfmakeraw, Up: Alphabetical List cfree ===== Syntax ------ #include <stdlib.h> void cfree(void *pointer); Description ----------- This function returns the memory allocated by calloc (*note calloc::.) to the heap. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- Complex *x = calloc(12, sizeof(Complex)); cfree(x); File: libc.info, Node: cfsetispeed, Next: cfsetospeed, Prev: cfree, Up: Alphabetical List cfsetispeed =========== Syntax ------ #include <termios.h> int cfsetispeed (struct termios *termiosp, speed_t speed); Description ----------- This function sets the input line speed stored in the structure TERMIOSP to SPEED. *Note Termios functions::, for more details about this structure and the baudrate values it supports. Note that the termios emulation handles console only, and that the baudrate values have no effect in this implementation. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX File: libc.info, Node: cfsetospeed, Next: cfsetspeed, Prev: cfsetispeed, Up: Alphabetical List cfsetospeed =========== Syntax ------ #include <termios.h> int cfsetospeed (struct termios *termiosp, speed_t speed); Description ----------- This function sets the output line speed stored in the structure TERMIOSP to SPEED. *Note Termios functions::, for more details about this structure and the baudrate values it supports. Note that the termios emulation handles console only, and that the baudrate values have no effect in this implementation. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX File: libc.info, Node: cfsetspeed, Next: cgets, Prev: cfsetospeed, Up: Alphabetical List cfsetspeed ========== Syntax ------ #include <termios.h> int cfsetspeed (struct termios *termiosp, speed_t speed); Description ----------- This function sets the input and output line speed stored in the structure TERMIOSP to SPEED. It is provided for compatibility only. Note that the termios emulation handles console only. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: cgets, Next: chdir, Prev: cfsetspeed, Up: Alphabetical List cgets ===== Syntax ------ #include <conio.h> char *cgets(char *_str); Description ----------- Get a string from the console. This will take advantage of any command-line editing TSRs. To use, you must pre-fill the first character of the buffer. The first character is the size of the buffer. On return, the second character is the number of characters read. The third character is the first character read. Return Value ------------ A pointer to the first character read. Portability ----------- not ANSI, not POSIX File: libc.info, Node: chdir, Next: _check_v2_prog, Prev: cgets, Up: Alphabetical List chdir ===== Syntax ------ #include <unistd.h> int chdir(const char *new_directory); Description ----------- This function changes the current directory to NEW_DIRECTORY. If a drive letter is specified, the current directory for that drive is changed and the current disk is set to that drive, else the current directory for the current drive is changed. Return Value ------------ Zero if the new directory exists, else nonzero and ERRNO set if error. Portability ----------- not ANSI, POSIX Example ------- if (chdir("/tmp")) perror("/tmp"); File: libc.info, Node: _check_v2_prog, Next: chmod, Prev: chdir, Up: Alphabetical List _check_v2_prog ============== Syntax ------ #include <sys/system.h> const _v2_prog_type *_check_v2_prog(const char *program, int fd); Description ----------- This function checks a given program for various known types of executables and/or other things. This function povides two differnt entry points. One is to call the function with a not `NULL' pointer as `program' (in this case `fd' is ignored), then the file named by `program' is opened and closed by `_check_v2_prog'. When you pass `NULL' as `program', then you have to pass a valid file handle in `fd' and `_check_v2_prog' uses that handle and does also not close the file on return. Return Value ------------ `_v2_prog_type' is defined in `sys/system.h' like the following: typedef struct { char magic[16]; int struct_length; char go32[16]; unsigned char buffer[0]; } _v1_stubinfo; typedef struct { union { unsigned version:8; /* The version of DJGPP created that COFF exe */ struct { unsigned minor:4; /* The minor version of DJGPP */ unsigned major:4; /* The major version of DJGPP */ } v; } version; unsigned object_format:4; /* What an object format */ # define _V2_OBJECT_FORMAT_UNKNOWN 0x00 # define _V2_OBJECT_FORMAT_COFF 0x01 unsigned exec_format:4; /* What an executable format */ # define _V2_EXEC_FORMAT_UNKNOWN 0x00 # define _V2_EXEC_FORMAT_COFF 0x01 # define _V2_EXEC_FORMAT_STUBCOFF 0x02 # define _V2_EXEC_FORMAT_EXE 0x03 # define _V2_EXEC_FORMAT_UNIXSCRIPT 0x04 unsigned valid:1; /* Only when nonzero all the information is valid */ unsigned has_stubinfo:1; /* When nonzero the stubinfo info is valid */ unsigned unused:14; _v1_stubinfo *stubinfo; } _v2_prog_type; The macros shown above can be used to test the different members of that structure for known values. *Warning:* Do not modify any of the data in this structure. After calling `_check_v2_prog' you should check at first the member `valid'. Only if this is nonzero you can be sure that all the other information in the struct is valid. The same is for the `stubinfo' member of the above struct, it is valid only, when `has_stubinfo' is nonzero. Portability ----------- not ANSI, not POSIX Example ------- To use the information returned in the struct you can use code like the following: #include <stdio.h> #include <sys/system.h> int main() { const _v2_prog_type *type; /* Since we pass a valid name, we can use -1 as the second argument */ type = _check_v2_prog ("foo", -1); /* There was something wrong */ if (!type->valid) { fprintf(stderr, "Could not check the file 'foo'. Giving up.\\n"); return 1; } /* Currently only the COFF format is valid to be a V2 executable */ if (type->object_format != _V2_OBJECT_FORMAT_COFF) { fprintf(stderr, "File 'foo' is not in COFF format\\n"); return 2; } /* The major version is not 2 */ if (type->version.v.major != 2) { fprintf(stderr, "File 'foo' is not from DJGPP 2.xx\\n"); return 3; } fprintf(stdout, "File 'foo' is a valid DJGPP 2.xx executable\\n"); if (type->exec_format == _V2_EXEC_FORMAT_STUBCOFF) { fprintf(stdout, "File 'foo' has a stub loader prepended\\n"); } return 0; } File: libc.info, Node: chmod, Next: _chmod, Prev: _check_v2_prog, Up: Alphabetical List chmod ===== Syntax ------ #include <sys/stat.h> int chmod(const char *path, mode_t mode); Description ----------- This function changes the mode (writable or write-only) of the specified file. The value of MODE can be a combination of one or more of the following: `S_IRUSR' Make the file readable `S_IWUSR' Make the file writable Other `S_I*' values could be included, but they will be ignored. Return Value ------------ Zero if the file exists and the mode was changed, else nonzero. Portability ----------- not ANSI, POSIX Example ------- chmod("/tmp/dj.dat", S_IWUSR|S_IRUSR); File: libc.info, Node: _chmod, Next: chown, Prev: chmod, Up: Alphabetical List _chmod ====== Syntax ------ #include <io.h> int _chmod(const char *filename, int func, mode_t mode); Description ----------- This is a direct connection to the MS-DOS chmod function call, int 0x21, %ax = 0x4300/0x4301. If FUNC is 0, then DOS is called with AX = 0x4300, which returns an attribute byte of a file. If FUNC is 1, then the attributes of a file are set as specified in MODE. Note that the directory and volume attribute bits must always be 0 when `_chmod()' is called with FUNC = 1, or else the call will fail. The third argument is optional when getting attributes. The attribute bits are defined as follows: Bit Meaning 76543210 .......1 Read-only ......1. Hidden .....1.. System ....1... Volume Label ...1.... Directory ..1..... Archive xx...... Reserved (used by some network redirectors) On platforms where the LFN API (*note LFN: _use_lfn.) is available, `_chmod' calls function 0x7143 of Interrupt 21h, to support long file names. Return Value ------------ If the file exists, `_chmod()' returns its attribute byte in case it succeded, or -1 in case of failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: chown, Next: chsize, Prev: _chmod, Up: Alphabetical List chown ===== Syntax ------ #include <unistd.h> int chown(const char *file, int owner, int group); Description ----------- This function does nothing under MS-DOS Return Value ------------ This function always returns zero if the file exists, else it returns -1 and sets ERRNO to `ENOENT'. Portability ----------- not ANSI, POSIX File: libc.info, Node: chsize, Next: cleanup_client, Prev: chown, Up: Alphabetical List chsize ====== Syntax ------ #include <io.h> int chsize(int handle, long size); Description ----------- Just calls ftruncate (*note ftruncate::.). Return Value ------------ Zero on success, -1 on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: cleanup_client, Next: _clear87, Prev: chsize, Up: Alphabetical List cleanup_client ============== Syntax ------ #include <debug/dbgcom.h> void cleanup_client (void); Description ----------- This functions is typically called when the debugged process exits or is aborted. It restores segment descriptors, closes file handles that were left open by the debuggee, frees protected-mode and conventional memory and any segment descriptors allocated by the debuggee, and restores the debugger's original signal handlers. File: libc.info, Node: _clear87, Next: clearerr, Prev: cleanup_client, Up: Alphabetical List _clear87 ======== Syntax ------ #include <float.h> unsigned int _clear87(void); Description ----------- Clears the floating point processor's exception flags. Return Value ------------ The previous status word. Portability ----------- not ANSI, not POSIX File: libc.info, Node: clearerr, Next: clock, Prev: _clear87, Up: Alphabetical List clearerr ======== Syntax ------ #include <stdio.h> void clearerr(FILE *stream); Description ----------- This function clears the EOF and error indicators for the file STREAM. Return Value ------------ None. Portability ----------- ANSI, POSIX Example ------- clearerr(stdout); File: libc.info, Node: clock, Next: close, Prev: clearerr, Up: Alphabetical List clock ===== Syntax ------ #include <time.h> clock_t clock(void); Description ----------- This function returns the number of clock ticks since an arbitrary time, actually, since the first call to `clock', which itself returns zero. The number of tics per second is CLOCKS_PER_SEC. Return Value ------------ The number of tics. Portability ----------- ANSI, POSIX Example ------- printf("%d seconds have elapsed\n", clock()/CLOCKS_PER_SEC); File: libc.info, Node: close, Next: _close, Prev: clock, Up: Alphabetical List close ===== Syntax ------ #include <unistd.h> int close(int fd); Description ----------- The open file associated with FD is closed. Return Value ------------ Zero if the file was closed, nonzero if FD was invalid or already closed. Portability ----------- not ANSI, POSIX Example ------- int fd = open("data", O_RDONLY); close(fd); File: libc.info, Node: _close, Next: closedir, Prev: close, Up: Alphabetical List _close ====== Syntax ------ #include <io.h> int _close(int fd); Description ----------- This is a direct connection to the MS-DOS close function call, int 0x21, %ah = 0x3e. This function can be hooked by the *Note File System Extensions::. If you don't want this, you should use *Note _dos_close::. Return Value ------------ Zero if the file was closed, else nonzero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: closedir, Next: clreol, Prev: _close, Up: Alphabetical List closedir ======== Syntax ------ #include <dirent.h> int closedir(DIR *dir); Description ----------- This function closes a directory opened by opendir (*note opendir::.). Return Value ------------ Zero on success, nonzero if DIR is invalid. Portability ----------- not ANSI, POSIX File: libc.info, Node: clreol, Next: clrscr, Prev: closedir, Up: Alphabetical List clreol ====== Syntax ------ #include <conio.h> void clreol(void); Description ----------- Clear to end of line. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: clrscr, Next: _conio_kbhit, Prev: clreol, Up: Alphabetical List clrscr ====== Syntax ------ #include <conio.h> void clrscr(void); Description ----------- Clear the entire screen. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _conio_kbhit, Next: _control87, Prev: clrscr, Up: Alphabetical List _conio_kbhit ============ Syntax ------ #include <conio.h> int _conio_kbhit(void); Description ----------- Determines whether or not a character is waiting at the keyboard. If there is an ungetch'd character, this function returns true. Note that if you include `conio.h', the *Note kbhit:: function is redefined to be this function instead. Return Value ------------ Nonzero if a key is waiting, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _control87, Next: cos, Prev: _conio_kbhit, Up: Alphabetical List _control87 ========== Syntax ------ #include <float.h> unsigned int _control87(unsigned int newcw, unsigned int mask); Description ----------- This function sets and retrieves the FPU's "control word". The control word is a special 16-bit register maintained by the math coprocessor. By setting and clearing bit fields in the control word, you can exercise control of certain aspects of coprocessor operation. The individual bits of the x87 control word are defined by macros in float.h, and shown in this table: ---- ---- --XX XXXX = MCW_EM - exception masks (1=handle exception internally, 0=fault) ---- ---- ---- ---X = EM_INVALID - invalid operation ---- ---- ---- --X- = EM_DENORMAL - denormal operand ---- ---- ---- -X-- = EM_ZERODIVIDE - divide by zero ---- ---- ---- X--- = EM_OVERFLOW - overflow ---- ---- ---X ---- = EM_UNDERFLOW - underflow ---- ---- --X- ---- = EM_INEXACT - rounding was required ---- --XX ---- ---- = MCW_PC - precision control ---- --00 ---- ---- = PC_24 - single precision ---- --10 ---- ---- = PC_53 - double precision ---- --11 ---- ---- = PC_64 - extended precision ---- XX-- ---- ---- = MCW_RC - rounding control ---- 00-- ---- ---- = RC_NEAR - round to nearest ---- 01-- ---- ---- = RC_DOWN - round towards -Inf ---- 10-- ---- ---- = RC_UP - round towards +Inf ---- 11-- ---- ---- = RC_CHOP - round towards zero ---X ---- ---- ---- = MCW_IC - infinity control (obsolete, always affine) ---0 ---- ---- ---- = IC_AFFINE - -Inf < +Inf ---1 ---- ---- ---- = IC_PROJECTIVE - -Inf == +Inf `_control87' uses the value of NEWCW and MASK variables together to determine which bits of the FPU's control word should be set, and to what values. For each bit in MASK that is set (equals to 1), the corresponding bit in NEWCW specifies the new value of the same bit in the FPU's control word, which `_control87' should set. Bits which correspond to reset (zero) bits in MASK are not changed in the FPU's control word. Thus, using a zero value for MASK retrieves the current value of the control word without changing it. The exception bits `MCW_EM' (the low-order 6 bits) of the control word define the exception *mask*. That is, if a certain bit is set, the corresponding exception will be masked, i.e., it will not generate an FP exception (which normally causes signal `SIGFPE' to be delivered). A masked exception will be handled internally by the coprocessor. In general, that means that it will generate special results, such as "NaN", Not-a-Number (e.g., when you attempt to compute a square root of a negative number), denormalized result (in case of underflow), or infinity (e.g., in the case of division by zero, or when the result overflows). By default, DJGPP startup code masks all FP exceptions. The precision-control field `MCW_PC' (bits 8 and 9) controls the internal precision of the coprocessor by selecting the number of precision bits in the mantissa of the FP numbers. The values `PC_24', `PC_53', and `PC_64' set the precision to 24, 53, and 64-bit mantissa, respectively. This feature of the coprocessor is for compatibility with the "IEEE 745 standard" and only affect the `FADD', `FSUB' `FSUBR', `FMUL', `FDIV', `FDIVR', and `FSQRT' instructions. Lowering the precision will *not* decrease the execution time of FP instructions. The `MCW_PC' field is set to use the full-precision 64-bit mantissa by the DJGPP startup code. The rounding-control field `MCW_RC' (bits 10 and 11) controls the type (round or chop) and direction (-Inf or +Inf) of the rounding. It only affects arithmetic instructions. Set to round-to-nearest state by the DJGPP startup code. The infinity-control bit `MCW_IC' has no effect on 80387 and later coprocessors. Return Value ------------ The previous control word. (Note that this is different from what `_control87' from the Borland C library which returns the *new* control word.) Portability ----------- not ANSI, not POSIX Example ------- /* mask all exceptions, except invalid operation */ _control87 (0x033e, 0xffff); File: libc.info, Node: cos, Next: cosh, Prev: _control87, Up: Alphabetical List cos === Syntax ------ #include <math.h> double cos(double x); Description ----------- This function computes the cosine of X (which should be given in radians). Return Value ------------ The cosine of X. If the absolute value of X is finite but greater than or equal to 2^63, the value is 1 (since for arguments that large each bit of the mantissa is more than `Pi'). If the value of X is infinite or `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX Accuracy -------- In general, this function's relative accuracy is about 1.7*10^(-16), which is close to the machine precision for a `double'. However, for arguments very close to `Pi/2' and its odd multiples, the relative accuracy can be many times worse, due to loss of precision in the internal FPU computations. Since cos(Pi/2) is zero, the absolute accuracy is still very good; but if your program needs to preserve high *relative* accuracy for such arguments, link with `-lm' and use the version of `cos' from `libm.a' which does elaborate argument reduction, but is about three times slower. File: libc.info, Node: cosh, Next: cprintf, Prev: cos, Up: Alphabetical List cosh ==== Syntax ------ #include <math.h> double cosh(double x); Description ----------- This function computes the hyperbolic sine of X. Return Value ------------ The hyperbolic cosine of X. If the value of X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. If the value of X is so large that the result would overflow a `double', the return value is `Inf' and `errno' is set to `ERANGE'. If X is either a positive or a negative infinity, the result is `+Inf', and `errno' is not changed. Portability ----------- ANSI, POSIX File: libc.info, Node: cprintf, Next: cputs, Prev: cosh, Up: Alphabetical List cprintf ======= Syntax ------ #include <conio.h> int cprintf(const char *_format, ...); Description ----------- Like `printf' (*note printf::.), but prints through the console, taking into consideration window borders and text attributes. There is currently a 2048-byte limit on the size of each individual cprintf call. Return Value ------------ The number of characters written. Portability ----------- not ANSI, not POSIX File: libc.info, Node: cputs, Next: creat, Prev: cprintf, Up: Alphabetical List cputs ===== Syntax ------ #include <conio.h> int cputs(const char *_str); Description ----------- Puts the string onto the console. The cursor position is updated. Return Value ------------ Zero on success. Portability ----------- not ANSI, not POSIX File: libc.info, Node: creat, Next: _creat, Prev: cputs, Up: Alphabetical List creat ===== Syntax ------ #include <fcntl.h> #include <sys/stat.h> /* for mode definitions */ int creat(const char *filename, mode_t mode); Description ----------- This function creates the given file and opens it for writing. If the file exists, it is truncated to zero size, unless it is read-only, in which case the function fails. If the file does not exist, it will be created read-only if MODE does not have `S_IWUSR' set. Return Value ------------ A file descriptor >= 0, or a negative number on error. Portability ----------- not ANSI, POSIX Example ------- int fd = creat("data", S_IRUSR|S_IWUSR); write(fd, buf, 1024); close(fd); File: libc.info, Node: _creat, Next: _creatnew, Prev: creat, Up: Alphabetical List _creat ====== Syntax ------ #include <io.h> int _creat(const char *path, int attrib); Description ----------- This is a direct connection to the MS-DOS creat function call, int 0x21, %ah = 0x3c. The file is set to binary mode. This function can be hooked by the "File System Extensions", see *Note File System Extensions::. If you don't want this, you should use `_dos_creat' (*note _dos_creat::.) or `_dos_creatnew' (*note _dos_creatnew::.). On platforms where the LFN API (*note LFN: _use_lfn.) is available, `_creat' calls function 0x716C of Interrupt 21h, to support long file names. Return Value ------------ The new file descriptor, else -1 on error. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _creatnew, Next: crlf2nl, Prev: _creat, Up: Alphabetical List _creatnew ========= Syntax ------ #include <fcntl.h> #include <dir.h> #include <io.h> int _creatnew(const char *path, int attrib, int flags); Description ----------- This function creates a file given by PATH and opens it, like `_creat' does, but only if it didn't already exist. If the named file exists, `_creatnew' fails. (In contrast, `_creat' opens existing files and overwrites their contents, see *Note _creat::.) The attributes of the created file are determined by ATTRIB. The file is usually given the normal attribute (00H). If ATTRIB is non-zero, additional attributes will be set. The following macros, defined on `<dir.h>', can be used to control the attributes of the created file (the associated numeric values appear in parentheses): `FA_RDONLY (1)' The file is created with the read-only bit set. `FA_HIDDEN (2)' The file is created with the hidden bit set. Such files will not appear in directory listings unless you use special options to the commands which list files. `FA_SYSTEM (4)' The file is created with the system bit set. Such files will not appear in directory listings unless you use special options to the commands which list files. Other bits (`FA_LABEL' and `FA_DIREC') are ignored by DOS. The argument FLAGS controls the sharing mode and the fine details of how the file is handled by the operating system. The following macros, defined on `<fcntl.h>', can be used for this (associated numeric values are given in parentheses): `SH_COMPAT (00h)' Opens the file in compatibility mode, which allows any other process to open the file and read from the file any number of times. `SH_DENYRW (10h)' Denies both read and write access by other processes. `SH_DENYWR (20h)' Denies write access by other processes. `SH_DENYRD (30h)' Denies read access by other processes. `SH_DENYNO (40h)' Allows read and write access by other processes, but prevents other processes from opening the file in compatibility mode. Note that the file is always open for both reading and writing; `_creatnew' ignores any bits in the lower nibble of FLAGS (`O_RDONLY', `O_WRONLY', etc.). `_creatnew' calls DOS function 716Ch when long file names are supported, 6C00h otherwise. (On DOS version 3.x, function 5B00h is called which ignores the value of FLAGS, since function 6C00h is only supported by DOS 4.0 and later.) The file handle returned by `_creatnew' is set to binary mode. This function can be hooked by the Filesystem Extensions handlers, as described in *Note File System Extensions::. If you don't want this, you should use `_dos_creatnew' (*note _dos_creatnew::.) instead. Return Value ------------ The new file descriptor, else -1 on error. Portability ----------- not ANSI, not POSIX File: libc.info, Node: crlf2nl, Next: __crt0_glob_function, Prev: _creatnew, Up: Alphabetical List crlf2nl ======= Syntax ------ #include <io.h> size_t crlf2nl(char *buf, ssize_t len); Description ----------- This function removes Ctrl-M characters from the given BUF. Return Value ------------ The number of characters remaining in the buffer are returned. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __crt0_glob_function, Next: __crt0_load_environment_file, Prev: crlf2nl, Up: Alphabetical List __crt0_glob_function ==================== Syntax ------ #include <crt0.h> char **__crt0_glob_function(char *_argument); Description ----------- If the application wishes to provide a wildcard expansion function, it should define a `__crt0_glob_function' function. It should return a list of the expanded values, or 0 if no expansion will occur. The startup code will free the returned pointer if it is nonzero. If no expander function is provided, wildcards will be expanded in the POSIX.1 style by the default `__crt0_glob_function' from the C library. To disable expansion, provide a `__crt0_glob_function' that always returns 0. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __crt0_load_environment_file, Next: __crt0_setup_arguments, Prev: __crt0_glob_function, Up: Alphabetical List __crt0_load_environment_file ============================ Syntax ------ #include <crt0.h> void __crt0_load_environment_file(char *_app_name); Description ----------- This function, provided by libc.a, does all the work required to load additional environment variables from the file `djgpp.env' whose full pathname is given by the `DJGPP' environment variable. If the application does not use environment variables, the programmer can reduce the size of the program image by providing a version of this function that does nothing. *Note __crt0_setup_arguments::. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __crt0_setup_arguments, Next: _crt0_startup_flags, Prev: __crt0_load_environment_file, Up: Alphabetical List __crt0_setup_arguments ====================== Syntax ------ #include <crt0.h> void __crt0_setup_arguments(void); Description ----------- This function, provided by libc.a, does all the work required to provide the two arguments passed to main() (usually `argc' and `argv'). If main() does not use these arguments, the programmer can reduce the size of the program image by providing a version of this function that does nothing. Note that since the default `__crt0_setup_arguments_function' will *not* expand wildcards inside quotes (`"' or `''), you can quote a part of the argument that doesn't include wildcards and still have them expanded. This is so you could use wildcard expansion with filenames which have embedded whitespace (on LFN filesystems). *Note __crt0_load_environment_file::. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _crt0_startup_flags, Next: cscanf, Prev: __crt0_setup_arguments, Up: Alphabetical List _crt0_startup_flags =================== Syntax ------ #include <crt0.h> int _crt0_startup_flags = ...; Description ----------- This variable can be used to determine what the startup code will (or will not) do when the program begins. This can be used to tailor the startup environment to a particular program. `_CRT0_FLAG_PRESERVE_UPPER_CASE' If set, `argv[0]' is left in whatever case it was. If not set, all characters are mapped to lower case. Note that if the `argv0' field in the "stubinfo" structure is present, the case of that part of `argv[0]' is not affected. `_CRT0_FLAG_USE_DOS_SLASHES' If set, reverse slashes (dos-style) are preserved in `argv[0]'. If not set, all reverse slashes are replaced with unix-style slashes. `_CRT0_FLAG_DROP_EXE_SUFFIX' If set, the `.exe' suffix is removed from the file name component of `argv[0]'. If not set, the suffix remains. `_CRT0_FLAG_DROP_DRIVE_SPECIFIER' If set, the drive specifier (e.g. `C:') is removed from the beginning of `argv[0]' (if present). If not set, the drive specifier remains. `_CRT0_FLAG_DISALLOW_RESPONSE_FILES' If set, response files (e.g. `@gcc.rf') are not expanded. If not set, the contents of the response files are used to create arguments. Note that if the file does not exist, that argument remains unexpanded. `_CRT0_FLAG_KEEP_QUOTES' If set, the quote characters `'', `"', and `\' will be retained in `argv[]' elements when processing command lines passed by DOS and via `system'. This is used by the `redir' program, and should only be needed if you want to get the original command line exactly as it was passed by the caller. `_CRT0_FLAG_FILL_SBRK_MEMORY' If set, fill `sbrk''d memory with a constant value. If not, memory gets whatever happens to have been in there, which breaks some applications. `_CRT0_FLAG_FILL_DEADBEEF' If set, fill memory (above) with `0xdeadbeef', else fill with zero. This is especially useful for debugging uninitialized memory problems. `_CRT0_FLAG_NEARPTR' If set, set DS limit to 4GB which allows use of near pointers to DOS (and other) memory. WARNING, disables memory protection and bad pointers may crash the machine or wipe out your data. This flag is silently ignored on NT and DOSEmu, which disallow such huge selector limits. `_CRT0_FLAG_NULLOK' If set, disable NULL pointer protection (if it can be controlled at all). `_CRT0_FLAG_NMI_SIGNAL' If set, enabled capture of NMI in exception code. This may cause problems with laptops and "green" boxes which use it to wake up. Default is to leave NMIs alone and pass through to real mode code. You decide. `_CRT0_FLAG_NO_LFN' If set, disable usage of long file name functions even on systems (such as Windows 9X) which support them. This might be needed to work around program assumptions on file name format on programs written specifically for DOS. Note that this flag overrides the value of the environment variable `LFN'. `_CRT0_FLAG_NONMOVE_SBRK' If set, the `sbrk' algorithm uses multiple DPMI memory blocks which makes sure the base of CS/DS/SS does not change. This may cause problems with `sbrk(0)' values and programs with other assumptions about `sbrk' behavior. This flag is useful with near pointers, since a constant pointer to DOS/Video memory can be computed without needing to reload it after any routine which might call `sbrk'. `_CRT0_FLAG_UNIX_SBRK' If set, the `sbrk' algorithm resizes memory blocks so that the layout of memory is set up to be the most compatible with Unix `sbrk' expectations. This mode should not be used with hardware interrupts, near pointers, and may cause problems with QDPMI virtual memory. On NT, this is the recommended algorithm. If your program requires a specific `sbrk' behavior, you should set either this or the previous flag, since the default may change in different libc releases. `_CRT0_FLAG_LOCK_MEMORY' If set, locks all memory as it is allocated. This effectively disables virtual memory, and may be useful if using extensive hardware interrupt codes in a relatively small image size. The memory is locked after it is `sbrk''ed, so the locking may fail. This bit may be set or cleared during execution. When `sbrk' uses multiple memory zones, it can be difficult to lock all memory since the memory block size and location is impossible to determine. `_CRT0_FLAG_PRESERVE_FILENAME_CASE' If set, disables all filename letter-case conversions in functions that traverse directories (except findfirst/findnext which always return the filenames exactly as found in the directory entry). When reset, all filenames on 8+3 MSDOS filesystems and DOS-style 8+3 filenames on LFN systems are converted to lower-case by functions such as `readdir', `getcwd', `_fixpath' and others. Note that when this flag is set, ALL filenames on MSDOS systems will appear in upper-case, which is both ugly and will break many Unix-born programs. Use only if you know exactly what you are doing! This flag overrides the value of the environment variable `FNCASE', *Note _preserve_fncase::. Portability ----------- not ANSI, not POSIX File: libc.info, Node: cscanf, Next: ctermid, Prev: _crt0_startup_flags, Up: Alphabetical List cscanf ====== Syntax ------ #include <conio.h> int cscanf(const char *_format, ...); Description ----------- Like `scanf' (*note scanf::.), but it reads from the standard input device directly, avoiding buffering both by DOS and by the library. Each character is read by `getche' (*note getche::.). Return Value ------------ The number of fields stored. Portability ----------- not ANSI, not POSIX File: libc.info, Node: ctermid, Next: ctime, Prev: cscanf, Up: Alphabetical List ctermid ======= Syntax ------ #include <unistd.h> char *ctermid(char *s); Description ----------- This function returns the name of the current terminal device. Under MS-DOS, this is always "con". Return Value ------------ If S is null, returns pointer to internal static string "con". Otherwise, copies "con" to buffer pointed by S. Portability ----------- not ANSI, POSIX File: libc.info, Node: ctime, Next: delay, Prev: ctermid, Up: Alphabetical List ctime ===== Syntax ------ #include <time.h> char *ctime(const time_t *cal); Description ----------- This function returns an ASCII representation of the time in CAL. This is equivalent to `asctime(localtime(cal))'. *Note asctime::. *Note localtime::. Return Value ------------ The ascii representation of the time. Portability ----------- ANSI, POSIX File: libc.info, Node: delay, Next: delline, Prev: ctime, Up: Alphabetical List delay ===== Syntax ------ #include <dos.h> void delay(unsigned msec); Description ----------- This function causes the program to pause for MSEC milliseconds. It uses the `int 15h' delay function to relinquish the CPU to other programs that might need it. Some operating systems that emulate DOS, such as OS/2 and Windows/NT, hang the DOS session when the <Pause> key is pressed during the call to `delay'. Plain DOS and Windows 3.X and 9X are known to not have this bug. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- delay(200); /* delay for 1/5 second */ File: libc.info, Node: delline, Next: _detect_80387, Prev: delay, Up: Alphabetical List delline ======= Syntax ------ #include <conio.h> void delline(void); Description ----------- The line the cursor is on is deleted; lines below it scroll up. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _detect_80387, Next: difftime, Prev: delline, Up: Alphabetical List _detect_80387 ============= Syntax ------ #include <dos.h> int _detect_80387(void); Description ----------- Detects whether a numeric coprocessor is present. Note that floating-point code will work even without a coprocessor, due to the existence of emulation. Return Value ------------ 1 if a coprocessor is present, 0 if not. Portability ----------- not ANSI, not POSIX Example ------- if (_detect_80387()) printf("You have a coprocessor\n"); File: libc.info, Node: difftime, Next: dirname, Prev: _detect_80387, Up: Alphabetical List difftime ======== Syntax ------ #include <time.h> double difftime(time_t t1, time_t t0); Description ----------- This function returns the difference in time, in seconds, from T0 to T1. Return Value ------------ The number of seconds. Portability ----------- ANSI, POSIX Example ------- time_t t1, t0; double elapsed; time(&t0); do_something(); time(&t1); elapsed = difftime(t1, t0); File: libc.info, Node: dirname, Next: disable, Prev: difftime, Up: Alphabetical List dirname ======= Syntax ------ #include <unistd.h> char * dirname (const char *fname); Description ----------- This function returns the directory part of the argument FNAME copied to a buffer allocated by calling `malloc'. The directory part is everything up to but not including the rightmost slash (either forward- or backslash) in FNAME. If FNAME includes a drive letter but no slashes, the function will return `X:.' where X is the drive letter. If FNAME includes neither the drive letter nor any slashes, `"."' will be returned. Trailing slashes are removed from the result, unless it is a root directory, with or without a drive letter. Return value ------------ The directory part in malloc'ed storage, or a NULL pointer of either there's not enough free memory, or FNAME is a NULL pointer. Portability ----------- not ANSI, not POSIX Example ------- printf ("The parent of current directory is %s\n", dirname (getcwd (0, PATH_MAX))); File: libc.info, Node: disable, Next: div, Prev: dirname, Up: Alphabetical List disable ======= Syntax ------ #include <dos.h> int disable(void); Description ----------- This function disables interrupts. *Note enable::. Return Value ------------ Returns nonzero if the interrupts had been enabled before this call, zero if they were already disabled. Portability ----------- not ANSI, not POSIX Example ------- int ints_were_enabled; ints_were_enabled = disable(); . . . do some stuff . . . if (ints_were_enabled) enable(); File: libc.info, Node: div, Next: __djgpp_exception_toggle, Prev: disable, Up: Alphabetical List div === Syntax ------ #include <stdlib.h> div_t div(int numerator, int denominator); Description ----------- Returns the quotient and remainder of the division NUMERATOR divided by DENOMINATOR. The return type is as follows: typedef struct { int quot; int rem; } div_t; Return Value ------------ The results of the division are returned. Portability ----------- ANSI, POSIX Example ------- div_t d = div(42, 3); printf("42 = %d x 3 + %d\n", d.quot, d.rem); div(+40, +3) = { +13, +1 } div(+40, -3) = { -13, -1 } div(-40, +3) = { -13, -1 } div(-40, -3) = { +13, -1 } File: libc.info, Node: __djgpp_exception_toggle, Next: __djgpp_map_physical_memory, Prev: div, Up: Alphabetical List __djgpp_exception_toggle ======================== Syntax ------ #include <sys/exceptn.h> void __djgpp_exception_toggle(void); Description ----------- This function is automatically called when the program exits, to restore handling of all the exceptions to their normal state. You may also call it from your program, around the code fragments where you need to temporarily restore *all* the exceptions to their default handling. One example of such case might be a call to a library functions that spawn child programs, when you don't want to handle signals generated while the child runs (by default, those signals are also passed to the parent). Portability ----------- not ANSI, not POSIX Example ------- __djgpp_exception_toggle(); system("myprog"); __djgpp_exception_toggle(); File: libc.info, Node: __djgpp_map_physical_memory, Next: __djgpp_memory_handle, Prev: __djgpp_exception_toggle, Up: Alphabetical List __djgpp_map_physical_memory =========================== Syntax ------ #include <dpmi.h> int __djgpp_map_physical_memory(void *our_addr, unsigned long num_bytes, unsigned long phys_addr); Description ----------- This function attempts to map a range of physical memory over the specified addresses. One common use of this routine is to map device memory, such as a linear frame buffer, into the address space of the calling program. OUR_ADDR, NUM_BYTES, and PHYS_ADDR must be page-aligned. If they are not page-aligned, ERRNO will be set to `EINVAL' and the routine will fail. This routine properly handles memory ranges that span multiple DPMI handles, while `__dpmi_map_device_in_memory_block' does not. Consult DPMI documentation on function 0508H for details on how this function works. Note: since 0508H is a DPMI service new with DPMI 1.0, this call will fail on most DPMI 0.9 servers. For your program to work on a wide range of systems, you should not assume this call will succeed. Even on failure, this routine may affect a subset of the pages specified. Return Value ------------ 0 on success, -1 on failure. On failure, ERRNO will be set to `EINVAL' for illegal input parameters, or `EACCES' if the DPMI server rejected the mapping request. Portability ----------- not ANSI, not POSIX Example ------- if (__djgpp_map_physical_memory (my_page_aligned_memory, 16384, 0x40000000)) printf ("Failed to map physical addresses!\n"); File: libc.info, Node: __djgpp_memory_handle, Next: __djgpp_memory_handle_list, Prev: __djgpp_map_physical_memory, Up: Alphabetical List __djgpp_memory_handle ===================== Syntax ------ #include <crt0.h> __djgpp_sbrk_handle *__djgpp_memory_handle(unsigned address); Description ----------- This function returns a pointer to a structure containing the memory handle and program relative offset associated with the address passed. It is just a convenient way to process the __djgpp_memory_handle_list. Return Value ------------ A pointer to the __djgpp_sbrk_handle associated with a particular address. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __djgpp_memory_handle_list, Next: __djgpp_nearptr_disable, Prev: __djgpp_memory_handle, Up: Alphabetical List __djgpp_memory_handle_list ========================== Syntax ------ #include <crt0.h> extern __djgpp_sbrk_handle __djgpp_memory_handle_list[256]; Description ----------- This array contains a list of memory handles and program relative offsets allocated by sbrk() in addition to the handle allocated by the stub. These values are normally not needed unless you are doing low-level DPMI page protection or memory mapping. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __djgpp_nearptr_disable, Next: __djgpp_nearptr_enable, Prev: __djgpp_memory_handle_list, Up: Alphabetical List __djgpp_nearptr_disable ======================= Syntax ------ #include <sys/nearptr.h> void __djgpp_nearptr_disable(void); Description ----------- This function disables near pointers, and re-enables protection. *Note __djgpp_nearptr_enable::. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __djgpp_nearptr_enable, Next: __djgpp_set_ctrl_c, Prev: __djgpp_nearptr_disable, Up: Alphabetical List __djgpp_nearptr_enable ====================== Syntax ------ #include <sys/nearptr.h> int __djgpp_nearptr_enable(void); Description ----------- This function enables "near pointers" to be used to access the DOS memory arena. Sort of. When you call this function, it will return nonzero if it has successfully enabled near pointers. If so, you must add the value `__djgpp_conventional_base' to the linear address of the physical memory. For example: if (__djgpp_nearptr_enable()) { short *screen = (short *)(__djgpp_conventional_base + 0xb8000); for (i=0; i<80*24*2; i++) screen[i] = 0x0720; __djgpp_nearptr_disable(); } The variable `__djgpp_base_address' contains the linear base address of the application's data segment. You can subtract this value from other linear addresses that DPMI functions might return in order to obtain a near pointer to those linear regions as well. If using the Unix-like sbrk algorithm, near pointers are only valid until the next `malloc', `system', `spawn*', or `exec*' function call, since the linear base address of the application may be changed by these calls. WARNING: When you enable near pointers, you disable all the protection that the system is providing. If you are not careful, your application may destroy the data in your computer. USE AT YOUR OWN RISK! Return Value ------------ Returns 0 if near pointers are not available, or nonzero if they are. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __djgpp_set_ctrl_c, Next: __djgpp_set_page_attributes, Prev: __djgpp_nearptr_enable, Up: Alphabetical List __djgpp_set_ctrl_c ================== Syntax ------ #include <sys/exceptn.h> int __djgpp_set_ctrl_c(int enable); Description ----------- This function sets and resets the bit which controls whether signals `SIGINT' and `SIGQUIT' (*note signal::.) will be raised when you press the INTR or QUIT keys. By default these generate signals which, if uncaught by a signal handler, will abort your program. However, when you call the `setmode' library function to switch the console reads to binary mode, or open the console in binary mode for reading, this generation of signals is turned off, because some programs want to get the `^C' and `^\' characters as any other character and handle them by themselves. `__djgpp_set_ctrl_c' lets you explicitly determine the effect of INTR and QUIT keys. When called with a non-zero, positive value of ENABLE, it arranges for `SIGINT' and `SIGQUIT' signals to be generated when the appropriate key is pressed; if you call it with a zero in ENABLE, these keys are treated as normal characters. If ENABLE is negative, `__djgpp_set_ctrl_c' returns the current state of the signal generation, but doesn't change it. For getting similar effects via the POSIX `termios' functions, see *Note tcsetattr::. Note that the effect of `Ctrl-<BREAK>' key is unaffected by this function; use the `_go32_want_ctrl_break' library function to control it. Also note that in DJGPP, the effect of the interrupt signal will only be seen when the program is in protected mode (*Note Signal Mechanism: signal, for more details). Thus, if you press `Ctrl-C' while your program calls DOS (e.g., when reading from the console), the `SIGINT' signal handler will only be called after that call returns. Return Value ------------ The state of `SIGINT' and `SIGQUIT' generation before the call: 0 if it was disabled, 1 if it was enabled. If the argument ENABLE is negative, the state is not altered. Portability ----------- not ANSI, not POSIX Example ------- setmode(fileno(stdin), O_BINARY); if (isatty(fileno(stdin))); __djgpp_set_ctrl_c(1); File: libc.info, Node: __djgpp_set_page_attributes, Next: __djgpp_set_sigint_key, Prev: __djgpp_set_ctrl_c, Up: Alphabetical List __djgpp_set_page_attributes =========================== Syntax ------ #include <dpmi.h> int __djgpp_set_page_attributes(void *our_addr, unsigned long num_bytes, unsigned short attributes); Description ----------- This function sets the DPMI page attributes for the pages in a range of memory. OUR_ADDR and NUM_BYTES must be page-aligned. If they are not page-aligned, ERRNO will be set to `EINVAL' and the routine will fail. Consult DPMI documentation on function 0507H for the meaning of the ATTRIBUTES argument. Note: since 0507H is a DPMI service new with DPMI 1.0, this call will fail on most DPMI 0.9 servers. For your program to work on a wide range of systems, you should not assume this call will succeed. Even on failure, this routine may affect a subset of the pages specified. Return Value ------------ 0 on success, -1 on failure. On failure, ERRNO will be set to `EINVAL' for illegal input parameters, or `EACCES' if the DPMI server rejected the attribute setting. Portability ----------- not ANSI, not POSIX Example ------- if (__djgpp_set_page_attributes (my_page_aligned_memory, 16384, 0)) printf ("Failed to make pages uncommitted!\n"); File: libc.info, Node: __djgpp_set_sigint_key, Next: __djgpp_set_sigquit_key, Prev: __djgpp_set_page_attributes, Up: Alphabetical List __djgpp_set_sigint_key ====================== Syntax ------ #include <sys/exceptn.h> void __djgpp_set_sigint_key(int new_key); Description ----------- This function changes the INTR key that generates the signal `SIGINT'. By default, `Ctrl-C' is set as the INTR key. To replace it with another key, put the *scan code* of the new INTR key into the bits 0-7 and the required keyboard status byte into bits 8-15 of NEW_KEY, and call this function. Here's how the keyboard status bits are defined: Bit 76543210 Meaning .......X Right Shift key ......X. Left Shift key .....X.. Ctrl key ....X... Alt key ...X.... Scroll Lock key ..X..... Num Lock key .X...... Caps Lock key X....... Insert A 1 in any of the above bits means that the corresponding key should be pressed; a zero means it should be released. Currently, all but the lower 4 bits are always ignored by the DJGPP keyboard handler when you set the INTR key using this function. For example, the default `Ctrl-C' key should be passed as `0x042e', since the scan code of the <C> key is 2Eh, and when the <Ctrl> key is pressed, the keyboard status byte is 04h. To disable `SIGINT' generation, pass zero as the argument (since no key has a zero scan code). This function will set things up so that the left <Shift> key doesn't affect Ctrl- and Alt-modified keys; the right <Shift> key won't affect them either, unless its bit is explicitly set in NEW_KEY. This means that `Ctrl-C' and `Ctrl-c' will both trigger `SIGINT' if `0x042e' is passed to this function. The DJGPP built-in keyboard handler pretends that when the right <Shift> key is pressed, so is the left <Shift> key (but not vice versa). For getting similar effects via the POSIX `termios' functions, see *Note tcsetattr::. Return Value ------------ The previous INTR key (scan code in bits 0-7, keyboad status in bits 8-15). Portability ----------- not ANSI, not POSIX Example ------- __djgpp_set_sigint_key(0x0422); /* make Ctrl-g generate SIGINT's */ File: libc.info, Node: __djgpp_set_sigquit_key, Next: __djgpp_share_flags, Prev: __djgpp_set_sigint_key, Up: Alphabetical List __djgpp_set_sigquit_key ======================= Syntax ------ #include <sys/exceptn.h> void __djgpp_set_sigquit_key(int new_key); Description ----------- This function changes the QUIT key that generates the signal `SIGQUIT'. By default, `Ctrl-\' is set as the QUIT key. To replace it with another key, put the *scan code* of the new QUIT key into the bits 0-7 and the required keyboard status byte into bits 8-15 of NEW_KEY, and call this function. Here's how the keyboard status bits are defined: Bit 76543210 Meaning .......X Right Shift key ......X. Left Shift key .....X.. Ctrl key ....X... Alt key ...X.... Scroll Lock key ..X..... Num Lock key .X...... Caps Lock key X....... Insert A 1 in any of the above bits means that the corresponding key should be pressed; a zero means it should be released. Currently, all but the lower 4 bits are always ignored by the DJGPP keyboard handler when you set the QUIT key with this function. For example, the default `Ctrl-\' key should be passed as `0x042b', since the scan code of `\' is 2Bh and when the <Ctrl> key is pressed, the keyboard status byte is 04h. To disable `SIGQUIT' generation, pass zero as the argument (since no key has a zero scan code). This function will set things up so that the left <Shift> key doesn't affect Ctrl- and Alt-modified keys; the right <Shift> key won't affect them either, unless its bit is explicitly set in NEW_KEY. This means that `Ctrl-\' and `Ctrl-|' will both trigger `SIGQUIT' if `0x042b' is passed to this function. The DJGPP built-in keyboard handler pretends that when the right <Shift> key is pressed, so is the left <Shift> key (but not vice versa). For getting similar effects via the POSIX `termios' functions, see *Note tcsetattr::. Return Value ------------ The previous QUIT key (scan code in bits 0-7, keyboad status in bits 8-15). Portability ----------- not ANSI, not POSIX Example ------- __djgpp_set_sigint_key(0); /* disable SIGQUIT's */ File: libc.info, Node: __djgpp_share_flags, Next: __djgpp_traceback_exit, Prev: __djgpp_set_sigquit_key, Up: Alphabetical List __djgpp_share_flags =================== Syntax ------ #include <fcntl.h> int __djgpp_share_flags = ...; Description ----------- This variable controls the share flags used by `open' (and hence `fopen') when opening a file. If you assign any value other than 0 to this variable libc will use that value for the sharing bits when if calls DOS to open the file. But if you specify any share flag in the `open' call then these flags will remain untouched. In this way `__djgpp_share_flags' acts just like a default and by default is 0 ensuring maximum compatibility with older versions of djgpp. If you don't know how the share flags act consult any DOS reference. They allow to share or protect a file when it's opened more than once by the same task or by two or more tasks. The exact behavior depends on the exact case. One interesting thing is that when the file is opened by two tasks under Windows the results are different if you use Windows 3.1 or Windows 95. To add even more complexity Windows 3.1 is affected by `SHARE.EXE'. The available flags are: `SH_COMPAT 0x0000' That's the compatible mode. `SH_DENYRW 0x0010' Deny read and deny write. `SH_DENYWR 0x0020' Deny write. `SH_DENYRD 0x0030' Deny read. `SH_DENYNO 0x0040' No deny. Of course these flags are DOS specific and doesn't exist under other OSs; and as you can imagine `__djgpp_share_flags' is djgpp specific. *Note open::. *Note fopen::. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __djgpp_traceback_exit, Next: _djstat_describe_lossage, Prev: __djgpp_share_flags, Up: Alphabetical List __djgpp_traceback_exit ====================== Syntax ------ #include <signal.h> void __djgpp_traceback_exit(int signo); Description ----------- This function is a signal handler which will print a traceback and abort the program. It is called by default by the DJGPP signal-handling code when any signal except `SIGQUIT' is raised (`SIGQUIT' is by default discarded). You can use this function to get the Unix behavior of aborting the program on `SIGQUIT' (see the example below). When this function is called directly, pass the signal number as its SIGNO argument. Portability ----------- not ANSI, not POSIX Example ------- signal(SIGQUIT, __djgpp_traceback_exit); File: libc.info, Node: _djstat_describe_lossage, Next: _djstat_fail_bits, Prev: __djgpp_traceback_exit, Up: Alphabetical List _djstat_describe_lossage ======================== Syntax ------ #include <stdio.h> void _djstat_describe_lossage(FILE *fp); Description ----------- Accesses the global variable *Note _djstat_fail_bits:: and prints to the stream given by FP a human-readable description of the undocumented DOS features which the last call to `stat()' or `fstat()' failed to use. (If FP is zero, the function prints to stderr.) If the last call to `f?stat()' didn't set any failure bits, an "all's well" message is printed. This function is designed to help in debugging these functions in hostile environments (like DOS clones) and in adapting them to the future DOS versions. If you ever have any strange results returned by `f?stat()', please call this function and post the diagnostics it printed to the DJGPP mailing list. The diagnostic messages this function prints are almost self-explanatory. Some explanations of terminology and abbreviations used by the printed messages will further clarify them. SDA ("Swappable DOS Area") - this is an internal DOS structure. `stat()' uses it to get the full directory entry (including the starting cluster number) of a file. The pointer to SDA found by `stat()' is trusted only if we find the pathname of our file at a specific offset in that SDA. SFT ("System File Table") - another internal DOS structure, used in file operations. `fstat()' uses it to get full information on a file given its handle. An SFT entry which is found by `fstat()' is only trusted if it contains files size and time stamp like those returned by DOS functions 57h and 42h. Novell NetWare 3.x traps DOS file operations in such a way they never get to SFT, so some failure messages refer specifically to Novell. Hashing - the fall-back method of returning a unique inode number for each file. It is used whenever the starting cluster of a file couldn't be reliably determined. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- if (stat(path, &stat_buf)) _djstat_describe_lossage((FILE *)0); File: libc.info, Node: _djstat_fail_bits, Next: _djstat_flags, Prev: _djstat_describe_lossage, Up: Alphabetical List _djstat_fail_bits ================= Syntax ------ #include <sys/stat.h> extern unsigned short _djstat_fail_bits; As proper operation of `stat' (*note stat::.) and `fstat' (*note fstat::.) depend on undocumented DOS features, they could fail in some incompatible environment or a future DOS version. If they do, the `_djstat_fail_bits' variable will have some of its bits set. Each bit describes a single feature which was used and failed. The function *Note _djstat_describe_lossage:: may be called to print a human-readable description of the bits which were set by the last call to `f?stat'. This should make debugging `f?stat' failures in an unanticipated environment a lot easier. The following bits are currently defined: `_STFAIL_SDA' Indicates that Get SDA call failed. `_STFAIL_OSVER' Indicates an unsupported DOS version (less than 3.10 for `stat' or less than 2.0 for `fstat'). `_STFAIL_BADSDA' The pointer to SDA was found to be bogus. `_STFAIL_TRUENAME' Indicates that `_truename' (*note _truename::.) function call failed. `_STFAIL_HASH' Indicates that the starting cluster of the file is unavailable, and inode number was computed by hashing its name. `_STFAIL_LABEL' The application requested the time stamp of a root dir, but no volume label was found. `_STFAIL_DCOUNT' The number of SDA reported is ridiculously large (probably an unsupported DOS clone). `_STFAIL_WRITEBIT' `fstat' was asked to get write access bit of a file, but couldn't. `_STFAIL_DEVNO' `fstat' failed to get device number. `_STFAIL_BADSFT' An SFT entry for this file was found by `fstat', but its contents can't be trusted because it didn't match file size and time stamp as reported by DOS. `_STFAIL_SFTIDX' The SFT index in Job File Table in program's PSP is negative. `_STFAIL_SFTNF' The file entry was not found in the SFT array. Below are some explanations of terminology and abbreviations used by the printed messages, which will further clarify the meaning of the above bits and their descriptions printed by `_djstat_describe_lossage' (*note _djstat_describe_lossage::.). SDA ("Swappable Data Area") - this is an internal DOS structure. `stat' uses it to get the full directory entry (including the starting cluster number) of a file. The pointer to SDA found by `stat' is trusted only if we find the pathname of our file at a specific offset in that SDA. SFT ("System File Table") - another internal DOS structure, used in file operations. `fstat' uses it to get full information on a file given its handle. An SFT entry which is found by `fstat' is only trusted if it contains files size and time stamp like those returned by DOS functions 57h and 42h. Novell NetWare 3.x traps DOS file operations in such a way they never get to SFT, so some failure messages refer specifically to Novell. Hashing - the fall-back method of returning a unique inode number for each file. It is used whenever the starting cluster of a file couldn't be reliably determined. The full pathname of the file is looked up in a table of files seen earlier (hashing is used to speed the lookup process). If found, the inode from the table is returned; this ensures that a given file will get the same inode number. Otherwise a new inode number is invented, recorded in the table and returned to caller. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _djstat_flags, Next: _doprnt, Prev: _djstat_fail_bits, Up: Alphabetical List _djstat_flags ============= Syntax ------ #include <sys/stat.h> extern unsigned short _djstat_flags; This variable contains bits for some fields of `struct stat' which are expensive to compute under DOS. Any such computation is only done by `stat' (*note stat::.) or `fstat' (*note fstat::.) if the corresponding bit in `_djstat_flags' is *cleared*. By default, all the bits are cleared, so applications which don't care, automagically get a full version, possibly at a price of performance. To get the fastest possible version for your application, clear only the bits which you need and set all the others. The following bits are currently defined: `_STAT_INODE' Causes `stat' and `fstat' to compute the `st_ino' (inode number) field. `_STAT_EXEC_EXT' Tells `stat' and `fstat' to compute the execute access bit from the file-name extension. `stat' and `fstat' know about many popular file-name extensions, to speed up the computation of the execute access bit. `_STAT_EXEC_MAGIC' Tells `stat' and `fstat' to compute the execute access bit from magic signature (the first two bytes of the file), see *Note _is_executable::, if the file-name extension is not enough for this. Computing the execute access bit from the magic signature is by far the most expensive part of `stat' and `fstat' (because it requires to read the first two bytes of every file). If your application doesn't care about execute access bit, setting `_STAT_EXEC_MAGIC' will significantly speed it up. Note that if `_STAT_EXEC_MAGIC' is set, but `_STAT_EXEC_EXT' is not, some files which shouldn't be flagged as executables (e.g., COFF `*.o' object files) will have their execute bit set, because they have the magic number signature at their beginning. Therefore, only use the above combination if you want to debug the list of extensions provided in `is_exec.c' file. `_STAT_DIRSIZE' Causes `stat' to compute directory size by counting the number of its entries (unless some friendly network redirector brought a true directory size with it). Also computes the number of subdirectories and sets the number of links `st_nlink' field. This computation is also quite expensive, especially for directories with large sub-directories. If your application doesn't care about size of directories and the `st_nlink' member, you should set the `_STAT_DIRSIZE' bit in `_djstat_flags'. `_STAT_ROOT_TIME' Causes `stat' to try to get time stamp of root directory from its volume label entry, if there is one. `_STAT_WRITEBIT' Tells `fstat' that file's write access bit is required (this needs special treatment only under some versions of Novell Netware). Note that if you set a bit, some failure bits in `_djstat_fail_bits' (*note _djstat_fail_bits::.) might not be set, because some computations which report failures are only done when they are required. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _doprnt, Next: _dos_close, Prev: _djstat_flags, Up: Alphabetical List _doprnt ======= Syntax ------ #include <stdio.h> int _doprnt(const char *format, void *params, FILE *file); Description ----------- This is an internal function that is used by all the `printf' style functions, which simply pass their format, arguments, and stream to this function. *Note printf::, for a discussion of the allowed formats and arguments. Return Value ------------ The number of characters generated is returned. Portability ----------- not ANSI, not POSIX Example ------- int args[] = { 1, 2, 3, 66 }; _doprnt("%d %d %d %c\n", args, stdout); File: libc.info, Node: _dos_close, Next: _dos_commit, Prev: _doprnt, Up: Alphabetical List _dos_close ========== Syntax ------ #include <dos.h> unsigned int _dos_close(int handle); Description ----------- This is a direct connection to the MS-DOS close function call (%ah = 0x3E). This function closes the specified file. *Note _dos_open::. *Note _dos_creat::. *Note _dos_creatnew::. *Note _dos_read::. *Note _dos_write::. Return Value ------------ Returns 0 if successful or DOS error code on error (and sets ERRNO). Portability ----------- not ANSI, not POSIX Example ------- int handle; _dos_creat("FOO.DAT", _A_ARCH, &handle); ... _dos_close(handle); File: libc.info, Node: _dos_commit, Next: _dos_creat, Prev: _dos_close, Up: Alphabetical List _dos_commit =========== Syntax ------ #include <dos.h> unsigned int _dos_commit(int handle); Description ----------- This is a direct connection to the MS-DOS commit function call (%ah = 0x68). This function flushes DOS internal file buffers to disk. Return Value ------------ Returns 0 if successful or DOS error code on error (and sets ERRNO). Portability ----------- not ANSI, not POSIX Example ------- _dos_write(handle, buffer, 1000, &result); _dos_commit(handle); _dos_close(handle); File: libc.info, Node: _dos_creat, Next: _dos_creatnew, Prev: _dos_commit, Up: Alphabetical List _dos_creat ========== Syntax ------ #include <dos.h> unsigned int _dos_creat(const char *filename, unsigned short attr, int *handle); Description ----------- This is a direct connection to the MS-DOS creat function call (%ah = 0x3C). This function creates the given file with the given attribute and puts file handle into HANDLE if creating is successful. If the file already exists it truncates the file to zero length. Meaning of ATTR parameter is the following: `_A_NORMAL (0x00)' Normal file (no read/write restrictions) `_A_RDONLY (0x01)' Read only file `_A_HIDDEN (0x02)' Hidden file `_A_SYSTEM (0x04)' System file `_A_ARCH (0x20)' Archive file See also *Note _dos_open::, *Note _dos_creatnew::, *Note _dos_read::, *Note _dos_write::, and *Note _dos_close::. This function does not support long filenames, even on systems where the LFN API (*note LFN: _use_lfn.) is available. For LFN-aware functions with similar functionality see *Note _creat::, and *Note _creatnew::. Also see *Note creat::, and *Note open::, which are Posix-standard. Return Value ------------ Returns 0 if successful or DOS error code on error (and sets ERRNO) Portability ----------- not ANSI, not POSIX Example ------- int handle; if ( !_dos_creat("FOO.DAT", _A_ARCH, &handle) ) puts("Creating was successful !"); File: libc.info, Node: _dos_creatnew, Next: _dos_findfirst, Prev: _dos_creat, Up: Alphabetical List _dos_creatnew ============= Syntax ------ #include <dos.h> unsigned int _dos_creatnew(const char *filename, unsigned short attr, int *handle); Description ----------- This is a direct connection to the MS-DOS create unique function call (%ah = 0x5B). This function creates the given file with the given attribute and puts file handle into HANDLE if creating is successful. This function will fail if the specified file exists. Meaning of ATTR parameter is the following: `_A_NORMAL (0x00)' Normal file (no read/write restrictions) `_A_RDONLY (0x01)' Read only file `_A_HIDDEN (0x02)' Hidden file `_A_SYSTEM (0x04)' System file `_A_ARCH (0x20)' Archive file See also *Note _dos_open::, *Note _dos_creat::, *Note _dos_read::, *Note _dos_write::, and *Note _dos_close::. This function does not support long filenames, even on systems where the LFN API (*note LFN: _use_lfn.) is available. For LFN-aware functions with similar functionality see *Note _creatnew::, and *Note _creat::. Also see *Note creat::, and *Note open::, which are Posix-standard. Return Value ------------ Returns 0 if successful or DOS error code on error (and sets ERRNO). Portability ----------- not ANSI, not POSIX Example ------- int handle; if ( !_dos_creatnew("FOO.DAT", _A_NORMAL, &handle) ) puts("Creating was successful !"); File: libc.info, Node: _dos_findfirst, Next: _dos_findnext, Prev: _dos_creatnew, Up: Alphabetical List _dos_findfirst ============== Syntax ------ #include <dos.h> unsigned int _dos_findfirst(char *name, unsigned int attr, struct find_t *result); Description ----------- This function and the related `_dos_findnext' (*note _dos_findnext::.) are used to scan directories for the list of files therein. The NAME is a wildcard that specifies the directory and files to search. RESULT is a structure to hold the results and state of the search, and ATTR is a combination of the following: `_A_NORMAL (0x00)' Normal file (no read/write restrictions) `_A_RDONLY (0x01)' Read only file `_A_HIDDEN (0x02)' Hidden file `_A_SYSTEM (0x04)' System file `_A_VOLID (0x08)' Volume ID file `_A_SUBDIR (0x10)' Subdirectory `_A_ARCH (0x20)' Archive file The results are returned in a `struct find_t' defined on `<dos.h>' as follows: struct find_t { char reserved[21]; unsigned char attrib; unsigned short wr_time; unsigned short wr_date; unsigned long size; char name[256]; }; *Note _dos_findnext::. This function does not support long filenames, even on systems where the LFN API (*note LFN: _use_lfn.) is available. For LFN-aware functions with similar functionality see *Note findfirst::, and *Note findnext::. Also see *Note opendir::, and *Note readdir::, which are Posix-standard. Return Value ------------ Zero if a match is found, DOS error code if not found (and sets ERRNO). Portability ----------- not ANSI, not POSIX Example ------- #include <dos.h> struct find_t f; if ( !_dos_findfirst("*.DAT", &f, _A_ARCH | _A_RDONLY) ) { do { printf("%-14s %10u %02u:%02u:%02u %02u/%02u/%04u\n", f.name, f.size, (f.wr_time >> 11) & 0x1f, (f.wr_time >> 5) & 0x3f, (f.wr_time & 0x1f) * 2, (f.wr_date >> 5) & 0x0f, (f.wr_date & 0x1f), ((f.wr_date >> 9) & 0x7f) + 1980); } while( !_dos_findnext(&f) ); } File: libc.info, Node: _dos_findnext, Next: _dos_getdate, Prev: _dos_findfirst, Up: Alphabetical List _dos_findnext ============= Syntax ------ #include <dos.h> unsigned int _dos_findnext(struct find_t *result); Description ----------- This finds the next file in the search started by `_dos_findfirst'. See *Note _dos_findfirst::, for the description of `struct find_t'. This function does not support long filenames, even on systems where the LFN API (*note LFN: _use_lfn.) is available. For LFN-aware functions with similar functionality see *Note findfirst::, and *Note findnext::. Also see *Note opendir::, and *Note readdir::, which are Posix-standard. Return Value ------------ Zero if a match is found, DOS error code if not found (and sets ERRNO). Portability ----------- not ANSI, not POSIX File: libc.info, Node: _dos_getdate, Next: _dos_getdiskfree, Prev: _dos_findnext, Up: Alphabetical List _dos_getdate ============ Syntax ------ #include <dos.h> void _dos_getdate(struct dosdate_t *date); Description ----------- This function gets the current date and fills the DATE structure with these values. struct dosdate_t { unsigned char day; /* 1-31 */ unsigned char month; /* 1-12 */ unsigned short year; /* 1980-2099 */ unsigned char dayofweek; /* 0-6, 0=Sunday */ }; *Note _dos_setdate::. *Note _dos_gettime::. *Note _dos_settime::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- struct dosdate_t date; _dos_getdate(&date); File: libc.info, Node: _dos_getdiskfree, Next: _dos_getdrive, Prev: _dos_getdate, Up: Alphabetical List _dos_getdiskfree ================ Syntax ------ #include <dos.h> unsigned int _dos_getdiskfree(unsigned int drive, struct diskfree_t *diskspace); Description ----------- This function determines the free space on DRIVE drive (0=default, 1=A:, 2=B:, etc.) and fills DISKSPACE structure. The members of `struct diskfree_t' are defined by `<dos.h>' as follows: struct diskfree_t { unsigned short total_clusters; unsigned short avail_clusters; unsigned short sectors_per_cluster; unsigned short bytes_per_sector; }; Return Value ------------ Returns with 0 if successful, non-zero on error (and sets `errno' to `EINVAL'). Portability ----------- not ANSI, not POSIX Example ------- struct diskfree_t df; unsigned long freebytes; if ( !_dos_getdiskfree(0, &df) ) { freebytes = (unsigned long)df.avail_clusters * (unsigned long)df.bytes_per_sector * (unsigned long)df.sectors_per_cluster; printf("There is %lu free bytes on the current drive.\n", freebytes); } else printf("Unable to get free disk space.\n"); File: libc.info, Node: _dos_getdrive, Next: _dos_getfileattr, Prev: _dos_getdiskfree, Up: Alphabetical List _dos_getdrive ============= Syntax ------ #include <dos.h> void _dos_getdrive(unsigned int *p_drive); Description ----------- This function determine the current default drive and writes this value into P_DRIVE (1=A:, 2=B:, etc.). *Note _dos_setdrive::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned int drive; _dos_getdrive(&drive); printf("The current drive is %c:.\n", 'A' - 1 + drive); File: libc.info, Node: _dos_getfileattr, Next: _dos_getftime, Prev: _dos_getdrive, Up: Alphabetical List _dos_getfileattr ================ Syntax ------ #include <dos.h> unsigned int _dos_getfileattr(const char *filename, unsigned int *p_attr); Description ----------- This function determines the attributes of given file and fills ATTR with it. Use the following constans (in DOS.H) to check this value. `_A_NORMAL (0x00)' Normal file (no read/write restrictions) `_A_RDONLY (0x01)' Read only file `_A_HIDDEN (0x02)' Hidden file `_A_SYSTEM (0x04)' System file `_A_VOLID (0x08)' Volume ID file `_A_SUBDIR (0x10)' Subdirectory `_A_ARCH (0x20)' Archive file *Note _dos_setfileattr::. This function does not support long filenames, even on systems where the LFN API (*note LFN: _use_lfn.) is available. For LFN-aware functions with similar functionality see *Note _chmod::. Also see *Note chmod::, *Note access::, and *Note stat::, which are Posix-standard. Return Value ------------ Returns with 0 if successful and DOS error value on error (and sets ERRNO=ENOENT). Portability ----------- not ANSI, not POSIX Example ------- unsigned int attr; if ( !_dos_getfileattr("FOO.DAT", &attr) ) { puts("FOO.DAT attributes are:"); if ( attr & _A_ARCH ) puts("Archive"); if ( attr & _A_RDONLY ) puts("Read only"); if ( attr & _A_HIDDEN ) puts("Hidden"); if ( attr & _A_SYSTEM ) puts("Is it part of DOS ?"); if ( attr & _A_VOLID ) puts("Volume ID"); if ( attr & _A_SUBDIR ) puts("Directory"); } else puts("Unable to get FOO.DAT attributes."); File: libc.info, Node: _dos_getftime, Next: _dos_gettime, Prev: _dos_getfileattr, Up: Alphabetical List _dos_getftime ============= Syntax ------ #include <dos.h> unsigned int _dos_getftime(int handle, unsigned int *p_date, unsigned *p_time); Description ----------- This function gets the date and time of the given file and puts these values into P_DATE and P_TIME variable. The meaning of DOS date in the P_DATE variable is the following: F E D C B A 9 8 7 6 5 4 3 2 1 0 (bits) X X X X X X X X X X X X X X X X *-----------------------* *-----------* *---------------* year month day year = 0-119 (relative to 1980) month = 1-12 day = 1-31 The meaning of DOS time in the P_TIME variable is the following: F E D C B A 9 8 7 6 5 4 3 2 1 0 X X X X X X X X X X X X X X X X *---------------* *-------------------* *---------------* hours minutes seconds hours = 0-23 minutes = 0-59 seconds = 0-29 in two-second intervals *Note _dos_setftime::. This function cannot be used to return last access and creation date and time, even on systems where the LFN API (*note LFN: _use_lfn.) is available. See *Note _lfn_get_ftime::, for a function that can be used to get the other two times. Also see *Note fstat::, which is Posix-standard. Return Value ------------ Returns 0 if successful and return DOS error on error (and sets ERRNO=EBADF). Portability ----------- not ANSI, not POSIX Example ------- unsigned int handle, date, time; _dos_open("FOO.DAT", O_RDWR, &handle); _dos_gettime(handle, &date, &time); _dos_close(handle); printf("FOO.DAT date and time is: %04u-%02u-%02u %02u:%02u:%02u.\n", /* year month day */ ((date >> 9) & 0x7F) + 1980U, (date >> 5) & 0x0F, date & 0x1F, /* hour minute second */ (time >> 11) & 0x1F, (time >> 5) & 0x3F, (time & 0x1F) * 2); File: libc.info, Node: _dos_gettime, Next: _dos_lock, Prev: _dos_getftime, Up: Alphabetical List _dos_gettime ============ Syntax ------ #include <dos.h> void _dos_gettime(struct dostime_t *time); Description ----------- This function gets the current time and fills the TIME structure with these values. struct dostime_t { unsigned char hour; /* 0-23 */ unsigned char minute; /* 0-59 */ unsigned char second; /* 0-59 */ unsigned char hsecond; /* 0-99 */ }; *Note _dos_settime::. *Note _dos_getdate::. *Note _dos_setdate::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- struct dostime_t time; _dos_gettime(&time); File: libc.info, Node: _dos_lock, Next: _dos_open, Prev: _dos_gettime, Up: Alphabetical List _dos_lock ========= Syntax ------ #include <io.h> int _dos_lock(int _fd, long _offset, long _length) Description ----------- Adds an advisory lock to the specified region of the file. Return Value ------------ Zero if the lock was added, nonzero otherwise. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _dos_open, Next: _dos_read, Prev: _dos_lock, Up: Alphabetical List _dos_open ========= Syntax ------ #include <fcntl.h> #include <share.h> #include <dos.h> unsigned int _dos_open(const char *filename, unsigned short mode, int *handle); Description ----------- This is a direct connection to the MS-DOS open function call (%ah = 0x3D). This function opens the given file with the given mode and puts handle of file into HANDLE if openning is successful. Meaning of MODE parameter is the following: Access mode bits (in FCNTL.H): `O_RDONLY (_O_RDONLY) 0x00' Open for read only `O_WRONLY (_O_WRONLY) 0x01' Open for write only `O_RDWR (_O_RDWR) 0x02' Open for read and write Sharing mode bits (in SHARE.H): `SH_COMPAT (_SH_COMPAT) 0x00' Compatibility mode `SH_DENYRW (_SH_DENYRW) 0x10' Deny read/write mode `SH_DENYWR (_SH_DENYWR) 0x20' Deny write mode `SH_DENYRD (_SH_DENYRD) 0x30' Deny read mode `SH_DENYNO (_SH_DENYNO) 0x40' Deny none mode Inheritance bits (in FCNTL.H): `O_NOINHERIT (_O_NOINHERIT) 0x80' File is not inherited by child process See also *Note _dos_creat::, *Note _dos_creatnew::, *Note _dos_read::, *Note _dos_write::, and *Note _dos_close::. This function does not support long filenames, even on systems where the LFN API (*note LFN: _use_lfn.) is available. For LFN-aware functions with similar functionality see *Note _open::, *Note _creat::, and *Note _creatnew::. Also see *Note open::, and *Note creat::, which are Posix-standard. Return Value ------------ Returns 0 if successful or DOS error code on error (and sets ERRNO to EACCES, EINVAL, EMFILE or ENOENT). Portability ----------- not ANSI, not POSIX Example ------- int handle; if ( !_dos_open("FOO.DAT", O_RDWR, &handle) ) puts("Wow, file opening was successful !"); File: libc.info, Node: _dos_read, Next: _dos_setdate, Prev: _dos_open, Up: Alphabetical List _dos_read ========= Syntax ------ #include <dos.h> unsigned int _dos_read(int handle, void *buffer, unsigned int count, unsigned int *result); Description ----------- This is a direct connection to the MS-DOS read function call (%ah = 0x3F). No conversion is done on the data; it is read as raw binary data. This function reads from HANDLE into BUFFER COUNT bytes. COUNT value may be arbitrary size (for example > 64KB). It puts number of bytes read into RESULT if reading is successful. See also *Note _dos_open::, *Note _dos_creat::, *Note _dos_creatnew::, *Note _dos_write::, and *Note _dos_close::. Return Value ------------ Returns 0 if successful or DOS error code on error (and sets ERRNO to EACCES or EBADF) Portability ----------- not ANSI, not POSIX Example ------- int handle; unsigned int result; char *filebuffer; if ( !_dos_open("FOO.DAT", O_RDONLY, &handle) ) { puts("FOO.DAT openning was successful."); if ( (filebuffer = malloc(130000)) != NULL ) { if ( !_dos_read(handle, buffer, 130000, &result) ) printf("%u bytes read from FOO.DAT.\n", result); else puts("Reading error."); ... /* Do something with filebuffer. */ ... } _dos_close(handle); } File: libc.info, Node: _dos_setdate, Next: _dos_setdrive, Prev: _dos_read, Up: Alphabetical List _dos_setdate ============ Syntax ------ #include <dos.h> unsigned int _dos_setdate(struct dosdate_t *date); Description ----------- This function sets the current date. The DOSDATE_T structure is as follows: struct dosdate_t { unsigned char day; /* 1-31 */ unsigned char month; /* 1-12 */ unsigned short year; /* 1980-2099 */ unsigned char dayofweek; /* 0-6, 0=Sunday */ }; DAYOFWEEK field has no effect at this function call. *Note _dos_getdate::. *Note _dos_gettime::. *Note _dos_settime::. Return Value ------------ Returns 0 if successful and non-zero on error (and sets ERRNO=EINVAL). Portability ----------- not ANSI, not POSIX Example ------- struct dosdate_t date; date->year = 1999; date->month = 12; date->day = 31; if ( !_dos_setdate(&date) ) puts("It was a valid date."); File: libc.info, Node: _dos_setdrive, Next: _dos_setfileattr, Prev: _dos_setdate, Up: Alphabetical List _dos_setdrive ============= Syntax ------ #include <dos.h> void _dos_setdrive(unsigned int drive, unsigned int *p_drives); Description ----------- This function set the current default drive based on DRIVE (1=A:, 2=B:, etc.) and determines the number of available logical drives and fills P_DRIVES with it. *Note _dos_getdrive::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned int available_drives; /* The current drive will be A: */ _dos_setdrive(1, &available_drives); printf("Number of available logical drives %u.\n", available_drives); File: libc.info, Node: _dos_setfileattr, Next: _dos_setftime, Prev: _dos_setdrive, Up: Alphabetical List _dos_setfileattr ================ Syntax ------ #include <dos.h> unsigned int _dos_setfileattr(const char *filename, unsigned int attr); Description ----------- This function sets the attributes of given file. Use the following constans in DOS.H to create ATTR parameter: `_A_NORMAL (0x00)' Normal file (no read/write restrictions) `_A_RDONLY (0x01)' Read only file `_A_HIDDEN (0x02)' Hidden file `_A_SYSTEM (0x04)' System file `_A_VOLID (0x08)' Volume ID file `_A_SUBDIR (0x10)' Subdirectory `_A_ARCH (0x20)' Archive file *Note _dos_getfileattr::. This function does not support long filenames, even on systems where the LFN API (*note LFN: _use_lfn.) is available. For LFN-aware functions with similar functionality see *Note _chmod::. Also see *Note chmod::, which is Posix-standard. Return Value ------------ Returns with 0 if successful and DOS error value on error (and sets ERRNO to ENOENT or EACCES). Portability ----------- not ANSI, not POSIX Example ------- if ( !_dos_setfileattr("FOO.DAT", _A_RDONLY | _A_HIDDEN) ) puts("FOO.DAT is hidden now."); File: libc.info, Node: _dos_setftime, Next: _dos_settime, Prev: _dos_setfileattr, Up: Alphabetical List _dos_setftime ============= Syntax ------ #include <dos.h> unsigned int _dos_setftime(int handle, unsigned int date, unsigned time); Description ----------- This function sets the date and time of the given file. The meaning of DOS date in the DATE variable is the following: F E D C B A 9 8 7 6 5 4 3 2 1 0 (bits) x x x x x x x x x x x x x x x x *-----------* *-----* *-------* year month day year = 0-119 (relative to 1980) month = 1-12 day = 1-31 The meaning of DOS time in the TIME variable is the following: F E D C B A 9 8 7 6 5 4 3 2 1 0 (bits) x x x x x x x x x x x x x x x x *-------* *---------* *-------* hours minutes seconds hours = 0-23 minutes = 0-59 seconds = 0-29 in two-second intervals *Note _dos_getftime::. This function cannot be used to set the last access date and time, even on systems where the LFN API (*note LFN: _use_lfn.) is available. For LFN-aware functions with similar functionality see *Note utime::, which is Posix-standard, and see *Note utimes::. Return Value ------------ Returns 0 if successful and return DOS error on error (and sets ERRNO=EBADF). Portability ----------- not ANSI, not POSIX Example ------- struct dosdate_t d; struct dostime_t t; unsigned int handle, date, time; _dos_open("FOO.DAT", O_RDWR, &handle); _dos_getdate(&d); _dos_gettime(&t); date = ((d.year - 1980) << 9) | (d.month << 5) | d.day; time = (t.hour << 11) | (t.minute << 5) | (t.second / 2); _dos_settime(handle, date, time); _dos_close(handle); File: libc.info, Node: _dos_settime, Next: _dos_unlock, Prev: _dos_setftime, Up: Alphabetical List _dos_settime ============ Syntax ------ #include <dos.h> void _dos_settime(struct dostime_t *time); Description ----------- This function sets the current time. The TIME structure is as follows: struct dostime_t { unsigned char hour; /* 0-23 */ unsigned char minute; /* 0-59 */ unsigned char second; /* 0-59 */ unsigned char hsecond; /* 0-99 */ }; *Note _dos_gettime::. *Note _dos_getdate::. *Note _dos_setdate::. Return Value ------------ Returns 0 if successful and non-zero on error (and sets ERRNO=EINVAL). Portability ----------- not ANSI, not POSIX Example ------- struct dostime_t time; time->hour = 23; time->minute = 59; time->second = 59; time->hsecond = 99; if ( !_dos_settime(&time) ) puts("It was a valid time."); File: libc.info, Node: _dos_unlock, Next: _dos_write, Prev: _dos_settime, Up: Alphabetical List _dos_unlock =========== Syntax ------ #include <io.h> _dos_unlock(int _fd, long _offset, long _length) Description ----------- Removes an advisory lock to the specified region of the file. Return Value ------------ Zero if the lock was removed, nonzero otherwise. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _dos_write, Next: _doscan, Prev: _dos_unlock, Up: Alphabetical List _dos_write ========== Syntax ------ #include <dos.h> unsigned int _dos_write(int handle, const void *buffer, unsigned int count, unsigned int *result); Description ----------- This is a direct connection to the MS-DOS write function call (%ah = 0x40). No conversion is done on the data; it is written as raw binary data. This function writes COUNT bytes from BUFFER to HANDLE. COUNT value may be arbitrary size (e.g. > 64KB). It puts the number of bytes written into RESULT if writing is successful. See also *Note _dos_open::, *Note _dos_creat::, *Note _dos_creatnew::, *Note _dos_read::, and *Note _dos_close::. Return Value ------------ Returns 0 if successful or DOS error code on error (and sets ERRNO to EACCES or EBADF) Portability ----------- not ANSI, not POSIX Example ------- int handle; unsigned int result; char *filebuffer; if ( !_dos_creat("FOO.DAT", _A_ARCH, &handle) ) { puts("FOO.DAT creating was successful."); if ( (filebuffer = malloc(130000)) != NULL ) { ... /* Put something into filebuffer. */ ... if ( !_dos_write(handle, buffer, 130000, &result) ) printf("%u bytes written into FOO.DAT.", result); else puts("Writing error."); } _dos_close(handle); } File: libc.info, Node: _doscan, Next: _doserrno, Prev: _dos_write, Up: Alphabetical List _doscan ======= Syntax ------ #include <stdio.h> int _doscan(FILE *file, const char *format, void **ptrs_to_args); Description ----------- This is an internal function that is used by all the `scanf' style functions, which simply pass their format, arguments, and stream to this function. *Note scanf::, for a discussion of the allowed formats and arguments. Return Value ------------ The number of characters successfully scanned is returned, or -1 on error. Portability ----------- not ANSI, not POSIX Example ------- int x, y; int *args[2]; args[0] = &x; args[1] = &y; _doscan(stdin, "%d %d", args); File: libc.info, Node: _doserrno, Next: dosexterr, Prev: _doscan, Up: Alphabetical List _doserrno ========= Syntax ------ #include <errno.h> extern int _doserrno; Description ----------- Whenever a DOS call returns a failure indication, this variable is assigned the value of the error code returned by the failed DOS call. For a list of the error codes and their short descriptions, see *Note dosexterr::. Portability ----------- not ANSI, not POSIX Example ------- _doserrno = 0; fprintf (stdprn, "Hello, world!\r\n\f"); if (_doserrno == 0x1c) fprintf (stderr, "The printer is out of paper!\n"); File: libc.info, Node: dosexterr, Next: dosmemget, Prev: _doserrno, Up: Alphabetical List dosexterr ========= Syntax ------ #include <dos.h> int dosexterr(struct DOSERROR *p_error); Description ----------- This function reads extended error information from DOS and fills P_ERROR structure. struct _DOSERROR { int exterror; char class; char action; char locus; }; Values for extended error code (EXTERROR field): 00h (0) no error 01h (1) function number invalid 02h (2) file not found 03h (3) path not found 04h (4) too many open files (no handles available) 05h (5) access denied 06h (6) invalid handle 07h (7) memory control block destroyed 08h (8) insufficient memory 09h (9) memory block address invalid 0Ah (10) environment invalid (usually >32K in length) 0Bh (11) format invalid 0Ch (12) access code invalid 0Dh (13) data invalid 0Eh (14) reserved 0Fh (15) invalid drive 10h (16) attempted to remove current directory 11h (17) not same device 12h (18) no more files 13h (19) disk write-protected 14h (20) unknown unit 15h (21) drive not ready 16h (22) unknown command 17h (23) data error (CRC) 18h (24) bad request structure length 19h (25) seek error 1Ah (26) unknown media type (non-DOS disk) 1Bh (27) sector not found 1Ch (28) printer out of paper 1Dh (29) write fault 1Eh (30) read fault 1Fh (31) general failure 20h (32) sharing violation 21h (33) lock violation 22h (34) disk change invalid (ES:DI -> media ID structure)(see below) 23h (35) FCB unavailable 24h (36) sharing buffer overflow 25h (37) (DOS 4+) code page mismatch 26h (38) (DOS 4+) cannot complete file operation (out of input) 27h (39) (DOS 4+) insufficient disk space 28h-31h reserved 32h (50) network request not supported 33h (51) remote computer not listening 34h (52) duplicate name on network 35h (53) network name not found 36h (54) network busy 37h (55) network device no longer exists 38h (56) network BIOS command limit exceeded 39h (57) network adapter hardware error 3Ah (58) incorrect response from network 3Bh (59) unexpected network error 3Ch (60) incompatible remote adapter 3Dh (61) print queue full 3Eh (62) queue not full 3Fh (63) not enough space to print file 40h (64) network name was deleted 41h (65) network: Access denied 42h (66) network device type incorrect 43h (67) network name not found 44h (68) network name limit exceeded 45h (69) network BIOS session limit exceeded 46h (70) temporarily paused 47h (71) network request not accepted 48h (72) network print/disk redirection paused 49h (73) network software not installed (LANtastic) invalid network version 4Ah (74) unexpected adapter close (LANtastic) account expired 4Bh (75) (LANtastic) password expired 4Ch (76) (LANtastic) login attempt invalid at this time 4Dh (77) (LANtastic v3+) disk limit exceeded on network node 4Eh (78) (LANtastic v3+) not logged in to network node 4Fh (79) reserved 50h (80) file exists 51h (81) reserved 52h (82) cannot make directory 53h (83) fail on INT 24h 54h (84) (DOS 3.3+) too many redirections 55h (85) (DOS 3.3+) duplicate redirection 56h (86) (DOS 3.3+) invalid password 57h (87) (DOS 3.3+) invalid parameter 58h (88) (DOS 3.3+) network write fault 59h (89) (DOS 4+) function not supported on network 5Ah (90) (DOS 4+) required system component not installed 64h (100) (MSCDEX) unknown error 65h (101) (MSCDEX) not ready 66h (102) (MSCDEX) EMS memory no longer valid 67h (103) (MSCDEX) not High Sierra or ISO-9660 format 68h (104) (MSCDEX) door open Values for error class (CLASS field): 01h out of resource (storage space or I/O channels) 02h temporary situation (file or record lock) 03h authorization (denied access) 04h internal (system software bug) 05h hardware failure 06h system failure (configuration file missing or incorrect) 07h application program error 08h not found 09h bad format 0Ah locked 0Bh media error 0Ch already exists 0Dh unknown Values for suggested action (ACTION field): 01h retry 02h delayed retry 03h prompt user to reenter input 04h abort after cleanup 05h immediate abort 06h ignore 07h retry after user intervention Values for error locus (LOCUS field): 01h unknown or not appropriate 02h block device (disk error) 03h network related 04h serial device (timeout) 05h memory related Return Value ------------ Returns with the extended error code. Portability ----------- not ANSI, not POSIX Example ------- #include <stdio.h> #include <dos.h> void main(void) { FILE *fp; struct _DOSERROR de; fp = fopen("EXAMPLE.DAT","r"); if ( fp == NULL ) { puts("Unable to open file for reading."); _dosexterr(&de); printf("Extended DOS error information:\n"); printf("Extended error: %i\n",de.exterror); printf("Class: %x\n",de.class); printf("Action: %x\n",de.action); printf("Error Locus: %x\n",de.locus); } } File: libc.info, Node: dosmemget, Next: dosmemgetb, Prev: dosexterr, Up: Alphabetical List dosmemget ========= Syntax ------ #include <sys/movedata.h> void dosmemget(int offset, int length, void *buffer); Description ----------- This function transfers data from MS-DOS's conventional memory space to the program's virtual address space. The OFFSET is a physical address, which can be computed from a real-mode segment/offset pair as follows: offset = segment * 16 + offset; The LENGTH is the number of bytes to transfer, and BUFFER is a pointer to somewhere in your virtual address space (such as memory obtained from `malloc') where the data will go. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned short shift_state; dosmemget(0x417, 2, &shift_state); if (shift_state & 0x0004) /* Ctrl key pressed */; File: libc.info, Node: dosmemgetb, Next: dosmemgetl, Prev: dosmemget, Up: Alphabetical List dosmemgetb ========== Syntax ------ #include <sys/movedata.h> void _dosmemgetb(unsigned long offset, size_t xfers, void *buffer); Description ----------- This function transfers data from MS-DOS's conventional memory space to the program's virtual address space, using only byte transfers. The OFFSET is a physical address, which can be computed from a real-mode segment/offset pair as follows: offset = segment * 16 + offset; The XFERS is the number of bytes to transfer, and BUFFER is a pointer to somewhere in your virtual address space (such as memory obtained from `malloc') where the data will go. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned short shift_state; _dosmemgetb(0x417, 2, &shift_state); if (shift_state & 0x0004) /* Ctrl key pressed */; File: libc.info, Node: dosmemgetl, Next: dosmemgetw, Prev: dosmemgetb, Up: Alphabetical List dosmemgetl ========== Syntax ------ #include <sys/movedata.h> void _dosmemgetl(unsigned long offset, size_t xfers, void *buffer); Description ----------- This function transfers data from MS-DOS's conventional memory space to the program's virtual address space, using only long-word (32-bit) transfers. The OFFSET is a physical address, which can be computed from a real-mode segment/offset pair as follows: offset = segment * 16 + offset; The COUNT is the number of long-words to transfer, and BUFFER is a pointer to somewhere in your virtual address space (such as memory obtained from `malloc') where the data will go. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned long shift_state; _dosmemgetl(0x417, 1, &shift_state); if (shift_state & 0x0004) /* Ctrl key pressed */; File: libc.info, Node: dosmemgetw, Next: dosmemput, Prev: dosmemgetl, Up: Alphabetical List dosmemgetw ========== Syntax ------ #include <sys/movedata.h> void _dosmemgetw(unsigned long offset, size_t xfers, void *buffer); Description ----------- This function transfers data from MS-DOS's conventional memory space to the program's virtual address space, using only short-word (16-bit) transfers. The OFFSET is a physical address, which can be computed from a real-mode segment/offset pair as follows: offset = segment * 16 + offset; The XFERS is the number of words to transfer, and BUFFER is a pointer to somewhere in your virtual address space (such as memory obtained from `malloc') where the data will go. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned short shift_state; _dosmemgetw(0x417, 1, &shift_state); if (shift_state & 0x0004) /* Ctrl key pressed */; File: libc.info, Node: dosmemput, Next: dosmemputb, Prev: dosmemgetw, Up: Alphabetical List dosmemput ========= Syntax ------ #include <sys/movedata.h> void dosmemput(const void *buffer, int length, int offset); Description ----------- This function transfers data from the program's virtual address space to MS-DOS's conventional memory space. The OFFSET is a physical address, which can be computed from a real-mode segment/offset pair as follows: offset = segment * 16 + offset; The LENGTH is the number of bytes to transfer, and BUFFER is a pointer to somewhere in your virtual address space (such as memory obtained from `malloc') where the data will come from. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned short save_screen[25][80]; dosmemput(save_screen, 80*2*25, 0xb8000); File: libc.info, Node: dosmemputb, Next: dosmemputl, Prev: dosmemput, Up: Alphabetical List dosmemputb ========== Syntax ------ #include <sys/movedata.h> void _dosmemputb(const void *buffer, size_t xfers, unsigned long offset); Description ----------- This function transfers data from the program's virtual address space to MS-DOS's conventional memory space, using only byte (8-bit) transfers. The OFFSET is a physical address, which can be computed from a real-mode segment/offset pair as follows: offset = segment * 16 + offset; The XFERS is the number of bytes to transfer, and BUFFER is a pointer to somewhere in your virtual address space (such as memory obtained from `malloc') where the data will come from. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned short save_screen[25][80]; _dosmemputb(save_screen, 0xb8000, 80*2*25); File: libc.info, Node: dosmemputl, Next: dosmemputw, Prev: dosmemputb, Up: Alphabetical List dosmemputl ========== Syntax ------ #include <sys/movedata.h> void _dosmemputl(const void *buffer, size_t xfers, unsigned long offset); Description ----------- This function transfers data from the program's virtual address space to MS-DOS's conventional memory space, using only long-word (32-bit) transfers. The OFFSET is a physical address, which can be computed from a real-mode segment/offset pair as follows: offset = segment * 16 + offset; The XFERS is the number of long-words to transfer, and BUFFER is a pointer to somewhere in your virtual address space (such as memory obtained from `malloc') where the data will come from. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned short save_screen[25][80]; _dosmemputl(save_screen, 40*25, 0xb8000); File: libc.info, Node: dosmemputw, Next: DPMI Overview, Prev: dosmemputl, Up: Alphabetical List dosmemputw ========== Syntax ------ #include <sys/movedata.h> void _dosmemputw(const void *buffer, size_t xfers, unsigned long offset); Description ----------- This function transfers data from the program's virtual address space to MS-DOS's conventional memory space, using only short-word (16-bit) transfers. The OFFSET is a physical address, which can be computed from a real-mode segment/offset pair as follows: offset = segment * 16 + offset; The XFERS is the number of short-words to transfer, and BUFFER is a pointer to somewhere in your virtual address space (such as memory obtained from `malloc') where the data will come from. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned short save_screen[25][80]; _dosmemputw(save_screen, 0xb8000, 80*25); File: libc.info, Node: DPMI Overview, Next: DPMI Specification, Prev: dosmemputw, Up: Alphabetical List DPMI Overview ============= extern unsigned short __dpmi_error; For most functions, the error returned from the DPMI server is stored in this variable. typedef struct { unsigned short offset16; unsigned short segment; } __dpmi_raddr; This structure is used to hold a real-mode address, which consists of a segment:offset pair. typedef struct { unsigned long offset32; unsigned short selector; } __dpmi_paddr; This structure is used to hold a protected-mode address, which consists of a selector:offset pair. typedef struct { unsigned long handle; /* 0, 2 */ unsigned long size; /* or count */ /* 4, 6 */ unsigned long address; /* 8, 10 */ } __dpmi_meminfo; This structure is used by many functions that need to refer to blocks of 32-bit memory. The `size' field doubles as a count for those operations that want a count of something, or return a count. typedef union { struct { unsigned long edi; unsigned long esi; unsigned long ebp; unsigned long res; unsigned long ebx; unsigned long edx; unsigned long ecx; unsigned long eax; } d; struct { unsigned short di, di_hi; unsigned short si, si_hi; unsigned short bp, bp_hi; unsigned short res, res_hi; unsigned short bx, bx_hi; unsigned short dx, dx_hi; unsigned short cx, cx_hi; unsigned short ax, ax_hi; unsigned short flags; unsigned short es; unsigned short ds; unsigned short fs; unsigned short gs; unsigned short ip; unsigned short cs; unsigned short sp; unsigned short ss; } x; struct { unsigned char edi[4]; unsigned char esi[4]; unsigned char ebp[4]; unsigned char res[4]; unsigned char bl, bh, ebx_b2, ebx_b3; unsigned char dl, dh, edx_b2, edx_b3; unsigned char cl, ch, ecx_b2, ecx_b3; unsigned char al, ah, eax_b2, eax_b3; } h; } __dpmi_regs; This structure is used by functions that pass register information, such as simulating real-mode calls. typedef struct { unsigned char major; unsigned char minor; unsigned short flags; unsigned char cpu; unsigned char master_pic; unsigned char slave_pic; } __dpmi_version_ret; This structure is used to return version information to the program. typedef struct { unsigned long largest_available_free_block_in_bytes; unsigned long maximum_unlocked_page_allocation_in_pages; unsigned long maximum_locked_page_allocation_in_pages; unsigned long linear_address_space_size_in_pages; unsigned long total_number_of_unlocked_pages; unsigned long total_number_of_free_pages; unsigned long total_number_of_physical_pages; unsigned long free_linear_address_space_in_pages; unsigned long size_of_paging_file_partition_in_pages; unsigned long reserved[3]; } __dpmi_free_mem_info; This structure is used to return information about the state of virtual memory in the system. typedef struct { unsigned long total_allocated_bytes_of_physical_memory_host; unsigned long total_allocated_bytes_of_virtual_memory_host; unsigned long total_available_bytes_of_virtual_memory_host; unsigned long total_allocated_bytes_of_virtual_memory_vcpu; unsigned long total_available_bytes_of_virtual_memory_vcpu; unsigned long total_allocated_bytes_of_virtual_memory_client; unsigned long total_available_bytes_of_virtual_memory_client; unsigned long total_locked_bytes_of_memory_client; unsigned long max_locked_bytes_of_memory_client; unsigned long highest_linear_address_available_to_client; unsigned long size_in_bytes_of_largest_free_memory_block; unsigned long size_of_minimum_allocation_unit_in_bytes; unsigned long size_of_allocation_alignment_unit_in_bytes; unsigned long reserved[19]; } __dpmi_memory_info; This is also used to return memory information, but by a different function. typedef struct { unsigned long data16[2]; unsigned long code16[2]; unsigned short ip; unsigned short reserved; unsigned long data32[2]; unsigned long code32[2]; unsigned long eip; } __dpmi_callback_info; This structure is used to install TSR programs. typedef struct { unsigned long size_requested; unsigned long size; unsigned long handle; unsigned long address; unsigned long name_offset; unsigned short name_selector; unsigned short reserved1; unsigned long reserved2; } __dpmi_shminfo; This structure is used to manipulate shared memory regions. File: libc.info, Node: DPMI Specification, Next: __dpmi_allocate_dos_memory, Prev: DPMI Overview, Up: Alphabetical List DPMI Specification ================== To obtain the DPMI specification, Contact Intel and order document number 240977-001. Also, try ftp.qdeck.com:/pub/memory/dpmi* and http://www.delorie.com/djgpp/doc/dpmi/. File: libc.info, Node: __dpmi_allocate_dos_memory, Next: __dpmi_allocate_ldt_descriptors, Prev: DPMI Specification, Up: Alphabetical List __dpmi_allocate_dos_memory ========================== Syntax ------ #include <dpmi.h> int __dpmi_allocate_dos_memory(int _paragraphs, int *_ret_selector_or_max); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0100 This function allocates DOS memory. You pass it the number of paragraphs ((bytes+15)>>4) to allocate. If it succeeds, it returns a segment (dos-style) and fills in _RET_SELECTOR_OR_MAX with a selector (protected-mode) that you can use to reference the same memory. Note that it's the selector you use to free the block, not the segment. Return Value ------------ -1 on error, else the segment [0000..FFFF]. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_allocate_ldt_descriptors, Next: __dpmi_allocate_linear_memory, Prev: __dpmi_allocate_dos_memory, Up: Alphabetical List __dpmi_allocate_ldt_descriptors =============================== Syntax ------ #include <dpmi.h> int __dpmi_allocate_ldt_descriptors(int count); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0000 Allocates COUNT descriptors. Return Value ------------ -1 on error, else the first descriptor. Use *Note __dpmi_get_selector_increment_value:: to figure out the remaining selectors. Portability ----------- not ANSI, not POSIX Example ------- short sel = __dpmi_allocate_ldt_descriptors(1); File: libc.info, Node: __dpmi_allocate_linear_memory, Next: __dpmi_allocate_memory, Prev: __dpmi_allocate_ldt_descriptors, Up: Alphabetical List __dpmi_allocate_linear_memory ============================= Syntax ------ #include <dpmi.h> int __dpmi_allocate_linear_memory(__dpmi_meminfo *info, int commit); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0504 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This allocates a block of page-aligned linear address space. Pass a desired address (or zero for any) and a size. COMMIT is 1 for committed pages, else they are uncommitted. It returns a handle and the actual address. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_allocate_memory, Next: __dpmi_allocate_real_mode_callback, Prev: __dpmi_allocate_linear_memory, Up: Alphabetical List __dpmi_allocate_memory ====================== Syntax ------ #include <dpmi.h> int __dpmi_allocate_memory(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0501 This allocates virtual memory. Fill in size, returns handle and address. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_allocate_real_mode_callback, Next: __dpmi_allocate_shared_memory, Prev: __dpmi_allocate_memory, Up: Alphabetical List __dpmi_allocate_real_mode_callback ================================== Syntax ------ #include <dpmi.h> int __dpmi_allocate_real_mode_callback(void (*_handler)(void), __dpmi_regs *_regs, __dpmi_raddr *_ret); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0303 This function gives you a real-mode address to pass to TSRs that gets reflected to your protected-mode handler. You pass it a register block to use; it gets filled in with the real-mode registers when your handler is called, and the registers are set from it when the handler returns. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_allocate_shared_memory, Next: __dpmi_allocate_specific_ldt_descriptor, Prev: __dpmi_allocate_real_mode_callback, Up: Alphabetical List __dpmi_allocate_shared_memory ============================= Syntax ------ #include <dpmi.h> int __dpmi_allocate_shared_memory(__dpmi_shminfo *info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0d00 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function allocates a shared memory block that can be accessed from different virtual machines. Fill the required length in `INFO->size_requested'. The function fills the rest of the structure: allocated length in `INFO->size', block handle in `INFO->handle', linear address in `INFO->address', and the selector:offset of an ASCIIZ block name (up to 128 bytes long) in `INFO->name_selector' and `INFO->name_offset', respectively. The access to the shared memory block can be serialized by calling the `__dpmi_serialize_on_shared_memory' function (*note __dpmi_serialize_on_shared_memory::.). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_allocate_specific_ldt_descriptor, Next: __dpmi_clear_debug_watchpoint, Prev: __dpmi_allocate_shared_memory, Up: Alphabetical List __dpmi_allocate_specific_ldt_descriptor ======================================= Syntax ------ #include <dpmi.h> int __dpmi_allocate_specific_ldt_descriptor(int _selector); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x000d This allocates the specific selector given. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_clear_debug_watchpoint, Next: __dpmi_create_alias_descriptor, Prev: __dpmi_allocate_specific_ldt_descriptor, Up: Alphabetical List __dpmi_clear_debug_watchpoint ============================= Syntax ------ #include <dpmi.h> int __dpmi_clear_debug_watchpoint(unsigned long _handle); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0b01 Clear a debug watchpoint. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_create_alias_descriptor, Next: __dpmi_discard_page_contents, Prev: __dpmi_clear_debug_watchpoint, Up: Alphabetical List __dpmi_create_alias_descriptor ============================== Syntax ------ #include <dpmi.h> int __dpmi_create_alias_descriptor(int _selector); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x000a Create a new selector with the same parameters as the given one. Return Value ------------ -1 on error, else the new selector. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_discard_page_contents, Next: __dpmi_free_dos_memory, Prev: __dpmi_create_alias_descriptor, Up: Alphabetical List __dpmi_discard_page_contents ============================ Syntax ------ #include <dpmi.h> int __dpmi_discard_page_contents(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0703 Advises the server that the given pages are no longer needed and may be reclaimed. Fill in address and size (in bytes). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_free_dos_memory, Next: __dpmi_free_ldt_descriptor, Prev: __dpmi_discard_page_contents, Up: Alphabetical List __dpmi_free_dos_memory ====================== Syntax ------ #include <dpmi.h> int __dpmi_free_dos_memory(int _selector); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0101 This function frees the dos memory allocated by *Note __dpmi_allocate_dos_memory::. Remember to pass the selector and not the segment. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_free_ldt_descriptor, Next: __dpmi_free_memory, Prev: __dpmi_free_dos_memory, Up: Alphabetical List __dpmi_free_ldt_descriptor ========================== Syntax ------ #include <dpmi.h> int __dpmi_free_ldt_descriptor(int descriptor); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0001 This function frees a single descriptor, even if it was allocated as one of many. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX Example ------- __dpmi_free_ldt_descriptor(sel); File: libc.info, Node: __dpmi_free_memory, Next: __dpmi_free_physical_address_mapping, Prev: __dpmi_free_ldt_descriptor, Up: Alphabetical List __dpmi_free_memory ================== Syntax ------ #include <dpmi.h> int __dpmi_free_memory(unsigned long _handle); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0502 This frees a block of virtual memory. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_free_physical_address_mapping, Next: __dpmi_free_real_mode_callback, Prev: __dpmi_free_memory, Up: Alphabetical List __dpmi_free_physical_address_mapping ==================================== Syntax ------ #include <dpmi.h> int __dpmi_free_physical_address_mapping(__dpmi_meminfo *info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0801 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function unmaps a physical device mapped with *Note __dpmi_physical_address_mapping::. Fill in the linear address. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_free_real_mode_callback, Next: __dpmi_free_serialization_on_shared_memory, Prev: __dpmi_free_physical_address_mapping, Up: Alphabetical List __dpmi_free_real_mode_callback ============================== Syntax ------ #include <dpmi.h> int __dpmi_free_real_mode_callback(__dpmi_raddr *_addr); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0303 This function frees the real-mode callback address. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_free_serialization_on_shared_memory, Next: __dpmi_free_shared_memory, Prev: __dpmi_free_real_mode_callback, Up: Alphabetical List __dpmi_free_serialization_on_shared_memory ========================================== Syntax ------ #include <dpmi.h> int __dpmi_free_serialization_on_shared_memory(unsigned long handle, int flags); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0d03 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function frees the serialization on shared memory block specified by its handle HANDLE. The bit-mapped variable FLAGS defines the following bits: bit 0 If set, release shared serialization (as opposed to exclusive serialization). bit 1 If set, free pending serialization. bits 2-15 Reserved (should be zero). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_free_shared_memory, Next: __dpmi_get_and_disable_virtual_interrupt_state, Prev: __dpmi_free_serialization_on_shared_memory, Up: Alphabetical List __dpmi_free_shared_memory ========================= Syntax ------ #include <dpmi.h> int __dpmi_free_shared_memory(unsigned long handle); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0d01 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function frees the shared memory block specified by the given HANDLE. The handle becomes invalid after this call. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_and_disable_virtual_interrupt_state, Next: __dpmi_get_and_enable_virtual_interrupt_state, Prev: __dpmi_free_shared_memory, Up: Alphabetical List __dpmi_get_and_disable_virtual_interrupt_state ============================================== Syntax ------ #include <dpmi.h> int __dpmi_get_and_disable_virtual_interrupt_state(void); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0900 This function disables interrupts, and returns the previous setting. Return Value ------------ The previous setting. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_and_enable_virtual_interrupt_state, Next: __dpmi_get_and_set_virtual_interrupt_state, Prev: __dpmi_get_and_disable_virtual_interrupt_state, Up: Alphabetical List __dpmi_get_and_enable_virtual_interrupt_state ============================================= Syntax ------ #include <dpmi.h> int __dpmi_get_and_enable_virtual_interrupt_state(void); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0901 This function enables interrupts, and returns the previous setting. Return Value ------------ The previous setting. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_and_set_virtual_interrupt_state, Next: __dpmi_get_capabilities, Prev: __dpmi_get_and_enable_virtual_interrupt_state, Up: Alphabetical List __dpmi_get_and_set_virtual_interrupt_state ========================================== Syntax ------ #include <dpmi.h> int __dpmi_get_and_set_virtual_interrupt_state(int _old_state); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AH = 0x09 This function restores the interrupt state from a previous call to *Note __dpmi_get_and_disable_virtual_interrupt_state:: or *Note __dpmi_get_and_enable_virtual_interrupt_state::. Return Value ------------ The previous setting. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_capabilities, Next: __dpmi_get_coprocessor_status, Prev: __dpmi_get_and_set_virtual_interrupt_state, Up: Alphabetical List __dpmi_get_capabilities ======================= Syntax ------ #include <dpmi.h> int __dpmi_get_capabilities(int *flags, char *vendor_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0401 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. Gets the capabilities of the server. FLAGS are as follows: ---- ---X = 1="page accessed/dirty" supported ---- --X- = 1="exceptions restartble" supported ---- -X-- = 1="device mapping" supported ---- X--- = 1="map conventional memory" supported ---X ---- = 1="demand zero-fill" supported --X- ---- = 1="write-protect client" supported -X-- ---- = 1="write-protect host" supported The vendor info is a 128-byte buffer: [0] host major number [1] host minor number [2..127] vendor name Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_coprocessor_status, Next: __dpmi_get_descriptor, Prev: __dpmi_get_capabilities, Up: Alphabetical List __dpmi_get_coprocessor_status ============================= Syntax ------ #include <dpmi.h> int __dpmi_get_coprocessor_status(void); Description ----------- Please refer to *Note DPMI Specification::, for details on DPMI function call operation. Also see *Note DPMI Overview::, for general information. DPMI function AX = 0x0e00 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. Return Value ------------ -1 on error, else returns the processor status flags. Here's the meaning of each set bit: bit 0 If set, co-processor is enabled. If reset, co-processor is disabled. bit 1 If set, the application is emulating the co-processor. bit 2 If set, the numeric co-processor is present. bit 3 If set, the DPMI host is emulating the co-processor. bits 4-7 The co-processor type: `0000' none `0010' 80287 `0011' 80387 `0100' 80486 with a numeric processor Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_descriptor, Next: __dpmi_get_descriptor_access_rights, Prev: __dpmi_get_coprocessor_status, Up: Alphabetical List __dpmi_get_descriptor ===================== Syntax ------ #include <dpmi.h> int __dpmi_get_descriptor(int _selector, void *_buffer); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x000b This function fills the 8-byte buffer pointed to by _BUFFER with the parameters of the descriptor whose selector is passed in _SELECTOR. The data has the following format: [0] XXXX XXXX = segment limit [7:0] [1] XXXX XXXX = segment limit [15:8] [2] XXXX XXXX = base address [7:0] [3] XXXX XXXX = base address [15:8] [4] XXXX XXXX = base address [23:16] [5] ---- XXXX = type; see details below [5] ---X ---- = 0=system, 1=application (must be 1) [5] -XX- ---- = privilege level, usually 3 (binary 11) [5] X--- ---- = 0=absent, 1=present; usually 1 [6] ---- XXXX = segment limit [19:16] [6] ---X ---- = available for user; see details below [6] --0- ---- = must be zero [6] -X-- ---- = 0=16-bit 1=32-bit; usually 1 [6] X--- ---- = 0=byte-granular (small) 1=page-granular (big) [7] XXXX XXXX = base address [31:24] Here's an alternative view of the layout that treats the buffer as an array of 4 16-bit words (i.e., `unsigned short's): [0] XXXX XXXX XXXX XXXX = segment limit [15:0] [1] XXXX XXXX XXXX XXXX = base address [15:0] [2] ---- ---- XXXX XXXX = base address [23:16] [2] ---- XXXX ---- ---- = type; see details below [2] ---1 ---- ---- ---- = 0=system, 1=application; must be 1 [2] -XX- ---- ---- ---- = privilege level, usually 3 (binary 11) [2] X--- ---- ---- ---- = 0=absent, 1=present; usually 1 [3] ---- ---- ---- XXXX = segment limit [19:16] [3] ---- ---- ---X ---- = available for user; see details below [3] ---- ---- --0- ---- = must be zero [3] ---- ---- -X-- ---- = 0=16-bit 1=32-bit; usually 1 [3] ---- ---- X--- ---- = 0=byte-granular (small) 1=page-granular (big) [3] XXXX XXXX ---- ---- = base address [31:24] Special considerations apply to some of the fields: Segment Limit fields The segment limit is specified as a 20-bit number. This number is interpreted as a number of bytes if the granularity bit (bit 7 of byte 6) is not set, and as a number of 4KB pages if the granularity bit is set. Offsets larger than the limit will generate a "GPF", the General Protection Fault exception. For expand-down data segments (see below), the segment limit is the *lower* limit of the segment; the upper limit is either 0xffffffff or 0xffff, depending on whether the size bit is set (32-bit default size) or not (16-bit default size). For expand-down segments, values of offset *less* than the segment limit result in a GPF. Base Address fields Segment base address should generally be 16-byte aligned. This is not required, but it maximizes performance by aligning code and data on 16-byte boundaries. Type field This field has different meanings depending on whether the descriptor is for code or data segment. For code segments, the meaning is as follows: ---X = 0=not accessed, 1=accessed --1- = 0=execute only, 1=execute/read; must be 1 -0-- = 0=non-conforming, 1=conforming; must be 0 1--- = 0=data segment, 1=code segment The accessed/not accessed bit indicates whether the segment has been accessed since the last time the bit was cleared. This bit is set whenever the segment selector is loaded into a segment register, and the bit then remains set until explicitly cleared. This bit can be used for debugging purposes. The read bit must be set to allow reading data from the code segment, which is done in several cases by the library. The DPMI spec (*note DPMI Specification::.) requires this bit to be 1 for code segments. The conforming bit must be cleared so that transfer of execution into this segment from a less-privileged segment will result in a GPF. The DPMI spec (*note DPMI Specification::.) requires this bit to be 0 for code segments. For data segments, the meaning of the `type' field is as follows: ---X = 0=not accessed, 1=accessed --X- = 0=read-only, 1=read/write -X-- = 0=expand-up, 1=expand-down; usually 0 0--- = 0=data segment, 1=code segment The accessed/not accessed bit has the same meaning as for code segments. The expand up/down bit is meant to be 1 for stack segments whose size should be changed dynamically, whereby changing the limit adds the additional space to the bottom of the stack; for data segments and statically-sized stack segments, this bit is usually zero. Present bit If this bit is clear, a segment-not-present exception will be generated when the selector is loaded into a segment register, and all the fields of the descriptor except the privilege level and the system/application bit are available for CPU/OS to store their own data. Don't clear this bit unless you know what you are doing. Available bit This bit is left for the application's use. It is neither set nor cleared by the DPMI server. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_descriptor_access_rights, Next: __dpmi_get_extended_exception_handler_vector_pm, Prev: __dpmi_get_descriptor, Up: Alphabetical List __dpmi_get_descriptor_access_rights =================================== Syntax ------ #include <dpmi.h> int __dpmi_get_descriptor_access_rights(int _selector); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. This function returns the access rights byte from the `lar' opcode. Return Value ------------ The access byte. *Note __dpmi_set_descriptor_access_rights::, for the details about the access information returned. Also see *Note __dpmi_get_descriptor::. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_extended_exception_handler_vector_pm, Next: __dpmi_get_extended_exception_handler_vector_rm, Prev: __dpmi_get_descriptor_access_rights, Up: Alphabetical List __dpmi_get_extended_exception_handler_vector_pm =============================================== Syntax ------ #include <dpmi.h> int __dpmi_get_extended_exception_handler_vector_pm(int vector, __dpmi_paddr *address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0210 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This gets the function that handles protected mode exceptions. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_extended_exception_handler_vector_rm, Next: __dpmi_get_free_memory_information, Prev: __dpmi_get_extended_exception_handler_vector_pm, Up: Alphabetical List __dpmi_get_extended_exception_handler_vector_rm =============================================== Syntax ------ #include <dpmi.h> int __dpmi_get_extended_exception_handler_vector_rm(int vector, __dpmi_paddr *address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0211 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function gets the handler for real-mode exceptions. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_free_memory_information, Next: __dpmi_get_memory_block_size_and_base, Prev: __dpmi_get_extended_exception_handler_vector_rm, Up: Alphabetical List __dpmi_get_free_memory_information ================================== Syntax ------ #include <dpmi.h> int __dpmi_get_free_memory_information(__dpmi_free_mem_info *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0500 This function returns information about available memory. Unsupported fields will have -1 (0xfffffff) in them. Return Value ------------ Zero. This always works. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_memory_block_size_and_base, Next: __dpmi_get_memory_information, Prev: __dpmi_get_free_memory_information, Up: Alphabetical List __dpmi_get_memory_block_size_and_base ===================================== Syntax ------ #include <dpmi.h> int __dpmi_get_memory_block_size_and_base(__dpmi_meminfo *info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x050a (DPMI 1.0 only). Not supported by CWSDPMI and Windows. Pass the handle. It fills in the address and size. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_memory_information, Next: __dpmi_get_multiple_descriptors, Prev: __dpmi_get_memory_block_size_and_base, Up: Alphabetical List __dpmi_get_memory_information ============================= Syntax ------ #include <dpmi.h> int __dpmi_get_memory_information(__dpmi_memory_info *buffer); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x050b (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function returns virtual memory information, as follows: `total_allocated_bytes_of_physical_memory_host' The total amount of allocated physical memory controlled by the DPMI host. `total_allocated_bytes_of_virtual_memory_host' The total amount of allocated virtual memory controlled by the DPMI host. `total_available_bytes_of_virtual_memory_host' The total amount of available virtual memory controlled by the DPMI host. `total_allocated_bytes_of_virtual_memory_vcpu' The amount of virtual memory allocated by the DPMI host for the current virtual machine. `total_available_bytes_of_virtual_memory_vcpu' The amount of virtual memory available for the current virtual machine. `total_allocated_bytes_of_virtual_memory_client' The amount of virtual memory allocated by the DPMI host for the current client (that is, for the calling program). `total_available_bytes_of_virtual_memory_client' The amount of virtual memory available to the current client. `total_locked_bytes_of_memory_client' The amount of memory locked by the calling program. `max_locked_bytes_of_memory_client' Maximum locked memory for the current client. `highest_linear_address_available_to_client' The highest linear address available to the calling program. `size_in_bytes_of_largest_free_memory_block' Size of the largest available memory block. `size_of_minimum_allocation_unit_in_bytes' Size of the smallest block that can be allocated. `size_of_allocation_alignment_unit_in_bytes' The alignment of allocated memory blocks. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_multiple_descriptors, Next: __dpmi_get_page_attributes, Prev: __dpmi_get_memory_information, Up: Alphabetical List __dpmi_get_multiple_descriptors =============================== Syntax ------ #include <dpmi.h> int __dpmi_get_multiple_descriptors(int count, void *buffer); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x000e (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function gets a list of selectors' parameters. The buffer pointed to by BUFFER must be prefilled with selector values, and will contain the parameters on return: [0x00:2] selector #1 (pass) [0x02:8] parameters #1 (returned) [0x0a:2] selector #2 (pass) [0x0c:8] parameters #2 (returned) ... Return Value ------------ Returns COUNT if successful, the negative of the number of descriptors copied if failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_page_attributes, Next: __dpmi_get_page_size, Prev: __dpmi_get_multiple_descriptors, Up: Alphabetical List __dpmi_get_page_attributes ========================== Syntax ------ #include <dpmi.h> int __dpmi_get_page_attributes(__dpmi_meminfo *info, short *buffer); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0506 (DPMI 1.0 only). Supported by CWSDPMI, but not by Windows. This function retrieves the attributes of a number of pages. Pass the handle in `INFO->handle', offset of first page (relative to start of block) in `INFO->address', and number of pages in `INFO->count'. The buffer BUFFER gets filled in with the attributes. For each page, a 16-bit attribute word in BUFFER defines the attributes of that page as follows: bits 0-2 Page type: `000' uncommitted `001' committed `010' mapped bit 3 If set, the page is read/write. If cleared, the page is read-only. bit 4 If set, bits 5 and 6 specify accessed and dirty bits. bit 5 The page has been accessed (only valid if bit 4 is set). bit 6 The page has been written (is "dirty"). Only valid if bit 4 is set. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_page_size, Next: __dpmi_get_processor_exception_handler_vector, Prev: __dpmi_get_page_attributes, Up: Alphabetical List __dpmi_get_page_size ==================== Syntax ------ #include <dpmi.h> int __dpmi_get_page_size(unsigned long *_size); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0604 Fills in the page size. Return Value ------------ -1 on error (16-bit host), else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_processor_exception_handler_vector, Next: __dpmi_get_protected_mode_interrupt_vector, Prev: __dpmi_get_page_size, Up: Alphabetical List __dpmi_get_processor_exception_handler_vector ============================================= Syntax ------ #include <dpmi.h> int __dpmi_get_processor_exception_handler_vector(int _vector, __dpmi_paddr *_address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0202 This function gets the current protected-mode exception handler (not interrupts) for the exception _VECTOR. It will return a selector:offset pair in the members of the _ADDRESS variable. Return Value ------------ -1 on error (invalid vector), else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_protected_mode_interrupt_vector, Next: __dpmi_get_raw_mode_switch_addr, Prev: __dpmi_get_processor_exception_handler_vector, Up: Alphabetical List __dpmi_get_protected_mode_interrupt_vector ========================================== Syntax ------ #include <dpmi.h> int __dpmi_get_protected_mode_interrupt_vector(int _vector, __dpmi_paddr *_address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0204 This function gets the address of the current protected mode interrupt (not exception) handler. It returns a selector:offset pair. Return Value ------------ Zero. This always works. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_raw_mode_switch_addr, Next: __dpmi_get_real_mode_interrupt_vector, Prev: __dpmi_get_protected_mode_interrupt_vector, Up: Alphabetical List __dpmi_get_raw_mode_switch_addr =============================== Syntax ------ #include <dpmi.h> int __dpmi_get_raw_mode_switch_addr(__dpmi_raddr *_rm, __dpmi_paddr *_pm); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0306 Read the spec for more info. Return Value ------------ Zero. This always works. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_real_mode_interrupt_vector, Next: __dpmi_get_segment_base_address, Prev: __dpmi_get_raw_mode_switch_addr, Up: Alphabetical List __dpmi_get_real_mode_interrupt_vector ===================================== Syntax ------ #include <dpmi.h> int __dpmi_get_real_mode_interrupt_vector(int _vector, __dpmi_raddr *_address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0200 This function stores the real-mode interrupt vector address in _ADDRESS. This is the same as the DOS get vector call, and returns a real-mode segment:offset pair. Bits [31:8] in the vector number are silently ignored. Return Value ------------ Zero. This function always works. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_segment_base_address, Next: __dpmi_get_segment_limit, Prev: __dpmi_get_real_mode_interrupt_vector, Up: Alphabetical List __dpmi_get_segment_base_address =============================== Syntax ------ #include <dpmi.h> int __dpmi_get_segment_base_address(int _selector, unsigned long *_addr); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0006 The physical base address of the selector is stored in *ADDR. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX Example ------- unsigned long addr; if (__dpmi_get_segment_base_address(selector, &addr)) ... File: libc.info, Node: __dpmi_get_segment_limit, Next: __dpmi_get_selector_increment_value, Prev: __dpmi_get_segment_base_address, Up: Alphabetical List __dpmi_get_segment_limit ======================== Syntax ------ #include <dpmi.h> unsigned __dpmi_get_segment_limit(int _selector); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. Return Value ------------ The limit of the segment, as returned by the `lsl' opcode. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_selector_increment_value, Next: __dpmi_get_state_of_debug_watchpoint, Prev: __dpmi_get_segment_limit, Up: Alphabetical List __dpmi_get_selector_increment_value =================================== Syntax ------ #include <dpmi.h> int __dpmi_get_selector_increment_value(void); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0003 Return Value ------------ The value to add to each selector allocated by __dpmi_allocate_ldt_descriptors to get the next one. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_state_of_debug_watchpoint, Next: __dpmi_get_state_save_restore_addr, Prev: __dpmi_get_selector_increment_value, Up: Alphabetical List __dpmi_get_state_of_debug_watchpoint ==================================== Syntax ------ #include <dpmi.h> int __dpmi_get_state_of_debug_watchpoint(unsigned long _handle, int *_status); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0b02 Gets the state of the watchpoint. Pass handle, fills in status (0=not encountered, 1=encountered). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_state_save_restore_addr, Next: __dpmi_get_vendor_specific_api_entry_point, Prev: __dpmi_get_state_of_debug_watchpoint, Up: Alphabetical List __dpmi_get_state_save_restore_addr ================================== Syntax ------ #include <dpmi.h> int __dpmi_get_state_save_restore_addr(__dpmi_raddr *_rm, __dpmi_paddr *_pm); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0305 Read the spec for info. Return Value ------------ The number of bytes required to save state. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_vendor_specific_api_entry_point, Next: __dpmi_get_version, Prev: __dpmi_get_state_save_restore_addr, Up: Alphabetical List __dpmi_get_vendor_specific_api_entry_point ========================================== Syntax ------ #include <dpmi.h> int __dpmi_get_vendor_specific_api_entry_point(char *_id, __dpmi_paddr *_api); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0a00 Look up a vendor-specific function, given the *name* of the function. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_version, Next: __dpmi_get_virtual_interrupt_state, Prev: __dpmi_get_vendor_specific_api_entry_point, Up: Alphabetical List __dpmi_get_version ================== Syntax ------ #include <dpmi.h> int __dpmi_get_version(__dpmi_version_ret *_ret); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0400 Fills in version information. The flags are as follows: ---- ---X = 0=16-bit host 1=32-bit host ---- --X- = 0=V86 used for reflected ints, 1=real mode ---- -X-- = 0=no virtual memory, 1=virtual memory supported The cpu is 2=80286, 3=80386, 4=80486, etc. DPMI 0.9 returns major=0 and minor=0x5a. Return Value ------------ Zero. This always works. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_get_virtual_interrupt_state, Next: __dpmi_install_resident_service_provider_callback, Prev: __dpmi_get_version, Up: Alphabetical List __dpmi_get_virtual_interrupt_state ================================== Syntax ------ #include <dpmi.h> int __dpmi_get_virtual_interrupt_state(void); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0902 Return Value ------------ This function returns the current interrupt flag (1=enabled). Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_install_resident_service_provider_callback, Next: __dpmi_int, Prev: __dpmi_get_virtual_interrupt_state, Up: Alphabetical List __dpmi_install_resident_service_provider_callback ================================================= Syntax ------ #include <dpmi.h> int __dpmi_install_resident_service_provider_callback(__dpmi_callback_info *info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0c00 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function installs a resident service provider callback and declares an intent to provide resident protected-mode services after terminating with a call to `__dpmi_terminate_and_stay_resident' (*note __dpmi_terminate_and_stay_resident::.). The various members of INFO should be filled as follows: `data16' An 8-byte descriptor for the 16-bit data segment. `code16' An 8-byte descriptor for the 16-bit code segment (zeros if not supported). `ip' A 16-bit offset of the 16-bit callback procedure. `data32' An 8-byte descriptor for 32-bit data segment. `code32' An 8-byte descriptor for 32-bit code segment (zeros if not supported). `eip' A 32-bit offset of the 32-bit callback procedure. *Note __dpmi_get_descriptor::, for the details about the layout of the 8-byte segment descriptor. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_int, Next: __dpmi_lock_linear_region, Prev: __dpmi_install_resident_service_provider_callback, Up: Alphabetical List __dpmi_int ========== Syntax ------ #include <dpmi.h> int __dpmi_int(int _vector, __dpmi_regs *_regs); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0300 This function performs a software interrupt in real mode after filling in *most* the registers from the given structure. %ss, %esp, and %eflags are automatically taken care of, unlike *Note __dpmi_simulate_real_mode_interrupt::. The following variables can be used to tune this function. By default, these variables are all zero. `__dpmi_int_ss' `__dpmi_int_sp' `__dpmi_int_flags' These hold the values stored in the appropriate field in the `__dpmi_regs' structure. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_lock_linear_region, Next: __dpmi_map_conventional_memory_in_memory_block, Prev: __dpmi_int, Up: Alphabetical List __dpmi_lock_linear_region ========================= Syntax ------ #include <dpmi.h> int __dpmi_lock_linear_region(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0600 This function locks virtual memory, to prevent page faults during hardware interrupts. Pass address and size (in bytes). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_map_conventional_memory_in_memory_block, Next: __dpmi_map_device_in_memory_block, Prev: __dpmi_lock_linear_region, Up: Alphabetical List __dpmi_map_conventional_memory_in_memory_block ============================================== Syntax ------ #include <dpmi.h> int __dpmi_map_conventional_memory_in_memory_block(__dpmi_meminfo *info, unsigned long physaddr); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0509 (DPMI 1.0 only). Supported by CWSDPMI, but not by Windows. This function maps conventional memory (even when virtualized) to virtual memory. Pass the handle, offset, and number of pages. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_map_device_in_memory_block, Next: __dpmi_mark_page_as_demand_paging_candidate, Prev: __dpmi_map_conventional_memory_in_memory_block, Up: Alphabetical List __dpmi_map_device_in_memory_block ================================= Syntax ------ #include <dpmi.h> int __dpmi_map_device_in_memory_block(__dpmi_meminfo *info, unsigned long *physaddr); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0508 (DPMI 1.0 only). Supported by CWSDPMI, but not by Windows. This function maps a physical address range to virtual memory. Pass the handle, offset relative to the start of the block, and number of pages to map. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_mark_page_as_demand_paging_candidate, Next: __dpmi_mark_real_mode_region_as_pageable, Prev: __dpmi_map_device_in_memory_block, Up: Alphabetical List __dpmi_mark_page_as_demand_paging_candidate =========================================== Syntax ------ #include <dpmi.h> int __dpmi_mark_page_as_demand_paging_candidate(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0702 Advises the server that certain pages are unlikely to be used soon. Set address and size (in bytes). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_mark_real_mode_region_as_pageable, Next: __dpmi_physical_address_mapping, Prev: __dpmi_mark_page_as_demand_paging_candidate, Up: Alphabetical List __dpmi_mark_real_mode_region_as_pageable ======================================== Syntax ------ #include <dpmi.h> int __dpmi_mark_real_mode_region_as_pageable(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0602 This function advises the host that the given pages are suitable for page-out. Pass address and size (in bytes). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_physical_address_mapping, Next: __dpmi_relock_real_mode_region, Prev: __dpmi_mark_real_mode_region_as_pageable, Up: Alphabetical List __dpmi_physical_address_mapping =============================== Syntax ------ #include <dpmi.h> int __dpmi_physical_address_mapping(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0800 Maps a physical device (like a graphics buffer) to linear memory. Fill in the physical address and size (in bytes). On return, the address is the linear address to use. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_relock_real_mode_region, Next: __dpmi_reset_debug_watchpoint, Prev: __dpmi_physical_address_mapping, Up: Alphabetical List __dpmi_relock_real_mode_region ============================== Syntax ------ #include <dpmi.h> int __dpmi_relock_real_mode_region(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0603 This function relocks the pages unlocked with *Note __dpmi_mark_real_mode_region_as_pageable::. Pass address and size (in bytes). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_reset_debug_watchpoint, Next: __dpmi_resize_dos_memory, Prev: __dpmi_relock_real_mode_region, Up: Alphabetical List __dpmi_reset_debug_watchpoint ============================= Syntax ------ #include <dpmi.h> int __dpmi_reset_debug_watchpoint(unsigned long _handle); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0b03 Resets a watchpoint given its handle in _HANDLE. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_resize_dos_memory, Next: __dpmi_resize_linear_memory, Prev: __dpmi_reset_debug_watchpoint, Up: Alphabetical List __dpmi_resize_dos_memory ======================== Syntax ------ #include <dpmi.h> int __dpmi_resize_dos_memory(int _selector, int _newpara, int *_ret_max); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0102 This function resizes a dos memory block. Remember to pass the selector, and not the segment. If this call fails, _RET_MAX contains the largest number of paragraphs available. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_resize_linear_memory, Next: __dpmi_resize_memory, Prev: __dpmi_resize_dos_memory, Up: Alphabetical List __dpmi_resize_linear_memory =========================== Syntax ------ #include <dpmi.h> int __dpmi_resize_linear_memory(__dpmi_meminfo *info, int commit); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0505 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function resizes a memory block. Pass the handle and new size. Bit 0 of COMMIT is 1 for committed pages; bit 1 is 1 to automatically update descriptors. It returns a new handle and base address. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_resize_memory, Next: __dpmi_segment_to_descriptor, Prev: __dpmi_resize_linear_memory, Up: Alphabetical List __dpmi_resize_memory ==================== Syntax ------ #include <dpmi.h> int __dpmi_resize_memory(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0503 This function changes the size of a virtual memory block. You must pass the handle and size fields. It may change the base address also; beware of debugging breakpoints and locked memory. It will return a new handle. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_segment_to_descriptor, Next: __dpmi_serialize_on_shared_memory, Prev: __dpmi_resize_memory, Up: Alphabetical List __dpmi_segment_to_descriptor ============================ Syntax ------ #include <dpmi.h> int __dpmi_segment_to_descriptor(int _segment); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0002 This function returns a selector that maps to what the real-mode segment provided would have referenced. Warning: this is a scarce resource. Return Value ------------ -1 on error, else the selector. Portability ----------- not ANSI, not POSIX Example ------- short video = __dpmi_segment_to_descriptor(0xa000); movedata(_my_ds(), buffer, video, 0, 320*200); File: libc.info, Node: __dpmi_serialize_on_shared_memory, Next: __dpmi_set_coprocessor_emulation, Prev: __dpmi_segment_to_descriptor, Up: Alphabetical List __dpmi_serialize_on_shared_memory ================================= Syntax ------ #include <dpmi.h> int __dpmi_serialize_on_shared_memory(unsigned long handle, int flags); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0d02 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function serializes access to a shared memory block whose handle is given in HANDLE. The bit-mapped variable FLAGS defines the following bits: bit 0 If set, return immediately if serialization is unavailable. If cleared, the program is suspended until the serialization becomes available. bit 1 If set, perform shared serialization. If cleared, perform exclusive serialization. bits 2-15 Reserved (should be zero). An "exclusive serialization" blocks *any* serialization attempts for the same memory block from other virtual machines. A "shared serialization" blocks only *exclusive* serialization attempts from other virtual machines. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_coprocessor_emulation, Next: __dpmi_set_debug_watchpoint, Prev: __dpmi_serialize_on_shared_memory, Up: Alphabetical List __dpmi_set_coprocessor_emulation ================================ Syntax ------ #include <dpmi.h> int __dpmi_set_coprocessor_emulation(int flags); Description ----------- Please refer to *Note DPMI Specification::, for details on DPMI function call operation. Also see *Note DPMI Overview::, for general information. DPMI function AX = 0x0e01 (DPMI v1.0 only, but supported by most DPMI v0.9 servers, including CWSDPMI, Windows, and QDPMI). This function sets the co-processor emulation state as specified by FLAGS. The only two used bits in FLAGS are: `bit 0' If set, enable the co-processor. If reset, disable the co-processor. `bit 1' If set, the emulation of the floating-point instructions will be done by the calling application. DJGPP programs using one of the provided emulators should generally call this functions with an argument of 2. (The DJGPP startup code does that automatically if no co-processor is detected.) Return Value ------------ -1 on errors, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_debug_watchpoint, Next: __dpmi_set_descriptor, Prev: __dpmi_set_coprocessor_emulation, Up: Alphabetical List __dpmi_set_debug_watchpoint =========================== Syntax ------ #include <dpmi.h> int __dpmi_set_debug_watchpoint(__dpmi_meminfo *_info, int _type); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0b00 Set a debug breakpoint. Type is 0 for execute, 1 for write, and 2 for access. Fill in address and size (1,2,4 bytes). Server fills in handle. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_descriptor, Next: __dpmi_set_descriptor_access_rights, Prev: __dpmi_set_debug_watchpoint, Up: Alphabetical List __dpmi_set_descriptor ===================== Syntax ------ #include <dpmi.h> int __dpmi_set_descriptor(int _selector, void *_buffer); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x000c This function sets the parameters of the selector _SELECTOR by copying the contents of the 8-byte buffer pointed to by _BUFFER into the LDT entry of the selector's descriptor. *Note __dpmi_get_descriptor::, for the description of the contents of the 8-byte buffer. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_descriptor_access_rights, Next: __dpmi_set_extended_exception_handler_vector_pm, Prev: __dpmi_set_descriptor, Up: Alphabetical List __dpmi_set_descriptor_access_rights =================================== Syntax ------ #include <dpmi.h> int __dpmi_set_descriptor_access_rights(int _selector, int _rights); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0009 This sets the access rights of _SELECTOR to _RIGHTS. The meaning of the individual bit fields of _RIGHTS is described below. For more details, please refer to *Note __dpmi_get_descriptor::. ---- ---- ---- ---X = 0=not accessed, 1=accessed ---- ---- ---- --X- = data: 0=read, 1=r/w; code: 1=readable ---- ---- ---- -X-- = data: 0=expand-up, 1=expand-down; code: 0=non-conforming ---- ---- ---- X--- = 0=data, 1=code ---- ---- ---1 ---- = must be 1 ---- ---- -XX- ---- = priviledge level (must equal CPL) ---- ---- X--- ---- = 0=absent, 1=present ---X ---- ---- ---- = available for the user --0- ---- ---- ---- = must be 0 -X-- ---- ---- ---- = 0=16-bit 1=32-bit X--- ---- ---- ---- = 0=byte granular (small) 1=page-granular (big) Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_extended_exception_handler_vector_pm, Next: __dpmi_set_extended_exception_handler_vector_rm, Prev: __dpmi_set_descriptor_access_rights, Up: Alphabetical List __dpmi_set_extended_exception_handler_vector_pm =============================================== Syntax ------ #include <dpmi.h> int __dpmi_set_extended_exception_handler_vector_pm(int vector, __dpmi_paddr *address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0212 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function installs a handler for protected-mode exceptions. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_extended_exception_handler_vector_rm, Next: __dpmi_set_multiple_descriptors, Prev: __dpmi_set_extended_exception_handler_vector_pm, Up: Alphabetical List __dpmi_set_extended_exception_handler_vector_rm =============================================== Syntax ------ #include <dpmi.h> int __dpmi_set_extended_exception_handler_vector_rm(int vector, __dpmi_paddr *address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0213 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function installs a handler for real-mode exceptions. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_multiple_descriptors, Next: __dpmi_set_page_attributes, Prev: __dpmi_set_extended_exception_handler_vector_rm, Up: Alphabetical List __dpmi_set_multiple_descriptors =============================== Syntax ------ #include <dpmi.h> int __dpmi_set_multiple_descriptors(int count, void *buffer); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x000f (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function sets multiple descriptors. Buffer usage is like in `__dpmi_get_multiple_descriptors' (*note __dpmi_get_multiple_descriptors::.), but the caller fills in everything before calling. Return Value ------------ Returns COUNT if successful, the negative of the number of descriptors set if failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_page_attributes, Next: __dpmi_set_processor_exception_handler_vector, Prev: __dpmi_set_multiple_descriptors, Up: Alphabetical List __dpmi_set_page_attributes ========================== Syntax ------ #include <dpmi.h> int __dpmi_set_page_attributes(__dpmi_meminfo *info, short *buffer); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0507 (DPMI 1.0 only). Supported by CWSDPMI, but not by Windows. This function sets attributes of a number of pages. Pass handle in `INFO->handle', offset within block in `INFO->address', and number of pages in `INFO->count'. BUFFER points to an array of 16-bit words which specify the new attributes. *Note __dpmi_get_page_attributes::, for the definition of the page attribute word. The DJGPP startup code calls this function to uncommit the so-called "null page", the first 4KB of the program's address space. This causes `NULL' pointer dereferences, a frequent programmatic error, to trigger a Page Fault exception, rather than go unnoticed. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_processor_exception_handler_vector, Next: __dpmi_set_protected_mode_interrupt_vector, Prev: __dpmi_set_page_attributes, Up: Alphabetical List __dpmi_set_processor_exception_handler_vector ============================================= Syntax ------ #include <dpmi.h> int __dpmi_set_processor_exception_handler_vector(int _vector, __dpmi_paddr *_address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0203 This function installs a handler for protected mode exceptions (not interrupts). You must pass a selector:offset pair. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_protected_mode_interrupt_vector, Next: __dpmi_set_real_mode_interrupt_vector, Prev: __dpmi_set_processor_exception_handler_vector, Up: Alphabetical List __dpmi_set_protected_mode_interrupt_vector ========================================== Syntax ------ #include <dpmi.h> int __dpmi_set_protected_mode_interrupt_vector(int _vector, __dpmi_paddr *_address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0205 This function installs a protected-mode interrupt (not exception) handler. You must pass a selector:offset pair. Hardware interrupts will always be reflected to protected mode if you install a handler. You must explicitely `sti' before `iret' because `iret' won't always restore interrupts in a virtual environment. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_real_mode_interrupt_vector, Next: __dpmi_set_segment_base_address, Prev: __dpmi_set_protected_mode_interrupt_vector, Up: Alphabetical List __dpmi_set_real_mode_interrupt_vector ===================================== Syntax ------ #include <dpmi.h> int __dpmi_set_real_mode_interrupt_vector(int _vector, __dpmi_raddr *_address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0201 This function sets a real-mode interrupt vector. You must pass a segment:offset pair, not a selector. Bits [31:8] in the vector number are silently ignored. Return Value ------------ Zero. This function always works. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_segment_base_address, Next: __dpmi_set_segment_limit, Prev: __dpmi_set_real_mode_interrupt_vector, Up: Alphabetical List __dpmi_set_segment_base_address =============================== Syntax ------ #include <dpmi.h> int __dpmi_set_segment_base_address(int _selector, unsigned _address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0007 This function sets the base address of the _SELECTOR to _ADDRESS. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_set_segment_limit, Next: __dpmi_simulate_real_mode_interrupt, Prev: __dpmi_set_segment_base_address, Up: Alphabetical List __dpmi_set_segment_limit ======================== Syntax ------ #include <dpmi.h> int __dpmi_set_segment_limit(int _selector, unsigned _address); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0008 This function sets the highest valid address in the segment referenced by _SELECTOR. For example, if you pass 0xfffff, the highest valid address is 0xfffff. Note: if you pass a number <= 64K, the segment changes to "non-big", and may cause unexpected problems. Limits for segments larger than 1MB must have their low 12 bits set. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_simulate_real_mode_interrupt, Next: __dpmi_simulate_real_mode_procedure_iret, Prev: __dpmi_set_segment_limit, Up: Alphabetical List __dpmi_simulate_real_mode_interrupt =================================== Syntax ------ #include <dpmi.h> int __dpmi_simulate_real_mode_interrupt(int _vector, __dpmi_regs *_regs); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0300 This function performs a software interrupt in real mode after filling in *all* the registers from the given structure. You *must* set %ss, %esp, and %eflags to valid real-mode values or zero, unlike *Note __dpmi_int::. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_simulate_real_mode_procedure_iret, Next: __dpmi_simulate_real_mode_procedure_retf, Prev: __dpmi_simulate_real_mode_interrupt, Up: Alphabetical List __dpmi_simulate_real_mode_procedure_iret ======================================== Syntax ------ #include <dpmi.h> int __dpmi_simulate_real_mode_procedure_iret(__dpmi_regs *_regs); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0302 This function switches to real mode, filling in *all* the registers from the structure. ss:sp and flags must be valid or zero. The called function must return with an `iret'. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_simulate_real_mode_procedure_retf, Next: __dpmi_simulate_real_mode_procedure_retf_stack, Prev: __dpmi_simulate_real_mode_procedure_iret, Up: Alphabetical List __dpmi_simulate_real_mode_procedure_retf ======================================== Syntax ------ #include <dpmi.h> int __dpmi_simulate_real_mode_procedure_retf(__dpmi_regs *_regs); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0301 This function switches to real mode with *all* the registers set from the structure, including cs:ip. The function called should return with a `retf'. ss:sp and flags must be set to valid values or zero. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_simulate_real_mode_procedure_retf_stack, Next: __dpmi_terminate_and_stay_resident, Prev: __dpmi_simulate_real_mode_procedure_retf, Up: Alphabetical List __dpmi_simulate_real_mode_procedure_retf_stack ============================================== Syntax ------ #include <dpmi.h> int __dpmi_simulate_real_mode_procedure_retf_stack(__dpmi_regs *_regs, int stack_words_to_copy, const void *stack_data); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0301 This function switches to real mode with *all* the registers set from the structure, including cs:ip. The function called should return with a `retf'. ss:sp and flags must be set to valid values or zero. You may optionally specify data to be copied to the real-mode stack, to pass arguments to real-mode procedures with stack-based calling conventions. If you don't want to copy data to the real mode stack, pass 0 for STACK_WORDS_TO_COPY, and `NULL' for STACK_BYTES. Note that the amount of stack data to be copied should be given in units of 16-bit words, not in bytes. This is defined by the underlying DPMI function. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_terminate_and_stay_resident, Next: __dpmi_unlock_linear_region, Prev: __dpmi_simulate_real_mode_procedure_retf_stack, Up: Alphabetical List __dpmi_terminate_and_stay_resident ================================== Syntax ------ #include <dpmi.h> int __dpmi_terminate_and_stay_resident(int return_code, int paragraphs_to_keep); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0c01 (DPMI 1.0 only). Not supported by CWSDPMI and Windows. This function terminates the calling program, but leaves it resident in memory. RETURN_CODE specifies which value to return to the OS. PARAGRAPHS_TO_KEEP specifies the number of paragraphs of DOS (conventional) memory to keep; it should be either zero or 6 or more. Note that any protected-mode memory remains allocated to the program unless explicitly freed before calling this function. The calling program *must* call the function `__dpmi_install_resident_service_provider_callback' before this one, otherwise it will be terminated instead of going TSR. *Note __dpmi_install_resident_service_provider_callback::. Return Value ------------ This call does not return. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_unlock_linear_region, Next: __dpmi_yield, Prev: __dpmi_terminate_and_stay_resident, Up: Alphabetical List __dpmi_unlock_linear_region =========================== Syntax ------ #include <dpmi.h> int __dpmi_unlock_linear_region(__dpmi_meminfo *_info); Description ----------- Please refer to *Note DPMI Specification:: for details on DPMI function call operation. Also see *Note DPMI Overview:: for general information. DPMI function AX = 0x0601 This function unlocks virtual memory. Pass address and size (in bytes). Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __dpmi_yield, Next: dup, Prev: __dpmi_unlock_linear_region, Up: Alphabetical List __dpmi_yield ============ Syntax ------ #include <dpmi.h> void __dpmi_yield(void); Description ----------- `__dpmi_yield' calls function 1680h of the interrupt 2Fh, which tells the task manager in a multitasking environment that the calling program doesn't need the rest of its time slice. The task manager will then preempt the calling program and switch to another task that is ready to run. This function should be called in busy-wait loops, like when a program waits for user input via keyboard, after it finds the keyboard buffer empty, to enhance overall performance in a multitasking environment. Return Value ------------ None. If the call isn't supported by the environment, like when running on plain DOS, `errno' is set to `ENOSYS'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: dup, Next: dup2, Prev: __dpmi_yield, Up: Alphabetical List dup === Syntax ------ #include <unistd.h> int dup(int old_handle); Description ----------- This function duplicates the given file handle. Both handles refer to the same file and file pointer. Return Value ------------ The new file handle, or -1 if error. Portability ----------- not ANSI, POSIX Example ------- do_file(dup(fileno(stdin))); File: libc.info, Node: dup2, Next: _dxe_load, Prev: dup, Up: Alphabetical List dup2 ==== Syntax ------ #include <unistd.h> int dup2(int existing_handle, int new_handle); Description ----------- This call causes NEW_HANDLE to refer to the same file and file pointer as EXISTING_HANDLE. If NEW_HANDLE is an open file, it is closed. Return Value ------------ The new handle, or -1 on error. Portability ----------- not ANSI, POSIX Example ------- /* copy new file to stdin stream */ close(0); dup2(new_stdin, 0); close(new_stdin); File: libc.info, Node: _dxe_load, Next: ecvt, Prev: dup2, Up: Alphabetical List _dxe_load ========= Syntax ------ #include <sys/dxe.h> void *_dxe_load(char *dxe_filename); Description ----------- This function loads a dynamic executable image, whose file name is pointed to by DXE_FILENAME, into memory and returns the entry point for the symbol associated with the image. The symbol may point to a structure or a function. Return Value ------------ 0 on failure, the address of the loaded symbol on success. Portability ----------- not ANSI, not POSIX Example ------- static int (*add)(int a, int b); add = _dxe_load("add.dxe"); if (add == 0) printf("Cannot load add.dxe\n"); else printf("Okay, 3 + 4 = %d\n", add(3,4)); File: libc.info, Node: ecvt, Next: ecvtbuf, Prev: _dxe_load, Up: Alphabetical List ecvt ==== Syntax ------ #include <stdlib.h> char * ecvt (double value, int ndigits, int *decpt, int *sign) Description ----------- This function converts the VALUE into a null-terminated string, and returns a pointer to that string. `ecvt' works exactly like `ecvtbuf' (*note ecvtbuf::.), except that it generates the string in an internal static buffer which is overwritten on each call. Return Value ------------ A pointer to the generated string. Portability ----------- not ANSI, not POSIX File: libc.info, Node: ecvtbuf, Next: edi_init, Prev: ecvt, Up: Alphabetical List ecvtbuf ======= Syntax ------ #include <stdlib.h> char * ecvtbuf (double value, int ndigits, int *decpt, int *sign, char *buf) Description ----------- This function converts its argument VALUE into a null-terminated string of NDIGITS digits in BUF. BUF should have enough space to hold at least `NDIGITS + 1' characters. The produced string in BUF does *not* include the decimal point. Instead, the position of the decimal point relative to the beginning of BUF is stored in an integer variable whose address is passed in DECPT. Thus, if BUF is returned as "1234" and *DECPT as 1, this corresponds to a value of 1.234; if *DECPT is -1, this corresponds to a value of 0.01234, etc. The sign is also not included in BUF's value. If VALUE is negative, `ecvtbuf' puts a nonzero value into the variable whose address is passed in SIGN; otherwise it stores zero in *SIGN. The least-significant digit in BUF is rounded. `ecvtbuf' produces the string "NaN" if VALUE is a NaN, and "Inf" or "Infinity" if VALUE is an infinity (the longer form is produced when NDIGITS is 8 or more). Return Value ------------ A pointer to BUF. Portability ----------- not ANSI, not POSIX Example ------- #include <stdlib.h> #include <stdio.h> #include <math.h> char vbuf[20]; int esign, edecpt; ecvtbuf (M_PI, 5, &edecpt, &esign, buf) /* This will print " 31416". */ printf ("%c%s", esign ? '-' : ' ', buf); File: libc.info, Node: edi_init, Next: enable, Prev: ecvtbuf, Up: Alphabetical List edi_init ======== Syntax ------ #include <debug/dbgcom.h> void edi_init (jmp_buf start_state); Description ----------- This function is part of the DJGPP "debugging support". It should be called after a call to `v2loadimage' (*note v2loadimage::.) which loads an executable program as a debuggee. `edi_init' then takes care of initializing the data structures which need to be set before the debugger can set breakpoints and run the debuggee. The argument START_STATE is usually set by a preceding call to `v2loadimage'. Portability ----------- not ANSI, not POSIX Example ------- if (v2loadimage (exec_file, cmdline, start_state)) { printf ("Load failed for image %s\n", exec_file); exit (1); } edi_init (start_state); File: libc.info, Node: enable, Next: endgrent, Prev: edi_init, Up: Alphabetical List enable ====== Syntax ------ #include <dos.h> int enable(void); Description ----------- This function enables interrupts. *Note disable::. Return Value ------------ Returns nonzero if the interrupts were already enabled, zero if they had been disabled before this call. Portability ----------- not ANSI, not POSIX Example ------- int ints_were_enabled; ints_were_enabled = enable(); . . . do some stuff . . . if (!ints_were_enabled) disable(); File: libc.info, Node: endgrent, Next: endmntent, Prev: enable, Up: Alphabetical List endgrent ======== Syntax ------ #include <grp.h> void endgrent(void); Description ----------- This function should be called after all calls to `getgrent', `getgrgid', or `getgrnam'. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- *Note getgrent::. File: libc.info, Node: endmntent, Next: endpwent, Prev: endgrent, Up: Alphabetical List endmntent ========= Syntax ------ #include <mntent.h> int endmntent(FILE *filep); Description ----------- This function should be called after the last call to `getmntent' (*note getmntent::.). Return Value ------------ This function always returns one. Portability ----------- not ANSI, not POSIX File: libc.info, Node: endpwent, Next: errno, Prev: endmntent, Up: Alphabetical List endpwent ======== Syntax ------ #include <pwd.h> void endpwent(void); Description ----------- This function should be called after the last call to getpwent (*note getpwent::.). Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: errno, Next: exec*, Prev: endpwent, Up: Alphabetical List errno ===== Syntax ------ #include <errno.h> extern int errno; Description ----------- This variable is used to hold the value of the error of the last function call. The value might be one of the following: `0' No Error. Library functions never set `errno' to zero, but the startup code does that just before calling `main' (this is ANSI C requirement). `1' EDOM - Numerical input to a function is out of range. `2' ERANGE - Numerical output of a function is out of range. `3' E2BIG - Argument list too long. `system' and the functions from the `spawn' family assign this to `errno' when the command line is too long (longer than 126-character limit when invoking non-DJGPP programs, or longer than the transfer buffer size when invoking DJGPP programs). `4' EACCES - Permission denied. Attempt to write to a read-only file, or remove a non-empty directory, or open a directory as if it were a file, etc. In essence, it's a DOS way of saying "You can't do that, but I'm too stupid to know why." `5' EAGAIN - Resource temporarily unavailable, try again later. Almost never used in DJGPP, except when DOS returns error code 3Dh ("network print queue full") 81h (NetWare4 "CWait children still running") or 9Bh (NetWare4 "unable to create another TCB"). `6' EBADF - Bad file descriptor: an invalid file handle passed to a library function. `7' EBUSY - Resource busy. Attempt to remove current directory (including current directory on another drive), or when a networked resource, such as a drive, is in use by another process. `8' ECHILD - No child processes. Returned by `wait' and `waitpid', and by NetWare-related calls. `9' EDEADLK - Resource deadlock avoided. Never used in DJGPP. `10' EEXIST - File exists. Returned by `open' and `mkdir' when a file or directory by that name already exists. `11' EFAULT - Bad address. A function was passed a bad pointer (like a `NULL' pointer). `12' EFBIG - File too large. Never used in DJGPP. `13' EINTR - Interrupted system call. `system' and the functions of the `spawn' family use that when the child program was interrupted by `Ctrl-<C>'. Also, when DOS returns the "fail on INT 24h" error code. `14' EINVAL - Invalid argument. Any case when any argument to a library function is found to be invalid. Examples include invalid drive number, "." or ".." as one of the arguments to `rename', syntax errors in the command line passed to `system', etc. `15' EIO - Input or output error. Low-level error in I/O operation, like bad disk block, damaged FAT, etc. `16' EISDIR - Is a directory: an attempt to do something with a directory which is only allowed with regular files. DOS usually returns `EACCES' in these cases, but DJGPP sometimes assigns `EISDIR' to `errno', like when `rename' is called to move a regular file over a directory, or when `system' or one of the `spawn*' functions are passed a name of a directory instead of an executable program. `17' EMFILE - Too many open files in system (no more handles available). This usually means that the number specified by the `FILES=' directive in `CONFIG.SYS' is too small. `18' EMLINK - Too many links. Not used in DJGPP (as DOS doesn't support links). `19' ENAMETOOLONG - File name too long (longer than `FILENAME_MAX', defined in `stdio.h'). `20' ENFILE - Too many open files. Never used in DJGPP. `21' ENODEV - No such device. Attempt to access an invalid drive, or an invalid operation for the type of drive. `22' ENOENT - No such file or directory. `23' ENOEXEC - Unable to execute file. Returned by `_dxe_load' (when the argument names a file that isn't a valid DXE), and by NetWare-related calls which run programs remotely. `24' ENOLCK - No locks available. Returned when the DOS file-locking functions cannot lock more files (due to overflow of the sharing buffer). `25' ENOMEM - Not enough memory. Note that, unlike your expectations, `malloc' does NOT set `errno' to `ENOMEM'; however, several library functions that use `malloc' will do that when it returns a `NULL' pointer. `26' ENOSPC - No space left on drive. DOS usually doesn't return this error, but `write' and `_write' do this for it, when they detect a full disk condition. `27' ENOSYS - Function not implemented. Any system call that isn't supported by the underlying OS, like an LFN function when running on plain DOS. `28' ENOTDIR - Not a directory. DOS never returns this code, but some library functions, like `rename' and `_truename', do that if they expect a valid directory pathname, but get either an invalid (e.g. empty) pathname or a file that is not a directory. `29' ENOTEMPTY - Directory not empty. DOS never returns this code, but `rename' does, when it is called to move a directory over an existing non-empty directory. `30' ENOTTY - Inappropriate I/O control operation. The "termios" functions set `errno' to this when called on a device that is not a TTY. `31' ENXIO - No such device or address. An operation attempted to reference a device (not a disk drive) that is invalid, or non-existent, or access a disk drive that exists but is empty. `32' EPERM - Operation not permitted. Examples include: sharing or file lock violations; denial of access to networked resources; expired password or illegal login attempts via a network; too many or duplicate network redirections; etc. `33' EPIPE - Broken pipe: attempt to write to a pipe with nobody to read it. This never happens in DJGPP. `34' EROFS - Read-only file system: attempt to write to a read-only disk. Unfortunately, DOS almost never returns this code. `35' ESPIPE - Invalid seek: attempt to seek on a pipe. Never happens in DJGPP, except for NetWare-related operations, since pipes are simulated with regular files in MS-DOS, and therefore are always seekable. `36' ESRCH - No such process. Not used in DJGPP. `37' EXDEV - Improper link. An attempt to rename a file across drives, or create a "symlink" to a file that is not an executable DJGPP v2.x program. `38' ENMFILE - No more files. `findfirst' and `findnext' assign this to `errno' when they exhaust the files in the directory. `readdir' does that as well. *Note perror::. Portability ----------- ANSI, POSIX File: libc.info, Node: exec*, Next: __exit, Prev: errno, Up: Alphabetical List exec* ===== Syntax ------ #include <unistd.h> int execl(const char *path, const char *argv0, ...); int execle(const char *path, const char *argv0, ... /*, char *const envp[] */); int execlp(const char *path, const char *argv0, ...); int execlpe(const char *path, const char *argv0, ... /*, char *const envp[] */); int execv(const char *path, char *const argv[]); int execve(const char *path, char *const argv[], char *const envp[]); int execvp(const char *path, char *const argv[]); int execvpe(const char *path, char *const argv[], char *const envp[]); Description ----------- These functions operate by calling `spawn*' with a type of `P_OVERLAY'. Refer to *Note spawn*:: for a full description. Return Value ------------ If successful, these functions do not return. If there is an error, these functions return -1 and set `errno' to indicate the error. Portability ----------- not ANSI, POSIX Example ------- execlp("gcc", "gcc", "-v", "hello.c", 0); File: libc.info, Node: __exit, Next: _exit, Prev: exec*, Up: Alphabetical List __exit ====== Syntax ------ #include <unistd.h> void __exit(int exit_code); Description ----------- This is an internal library function which exits the program, returning EXIT_CODE to the calling process. No additional processing is done, and any `atexit' functions are not called. Since hardware interrupts are not unhooked, this can cause crashes after the program exits. This function is normally called only by `_exit'; do *not* call it directly. Return Value ------------ This function does not return. Portability ----------- not ANSI, POSIX File: libc.info, Node: _exit, Next: exit, Prev: __exit, Up: Alphabetical List _exit ===== Syntax ------ #include <unistd.h> void _exit(int exit_code); Description ----------- This function exits the program, returning EXIT_CODE to the calling process. No additional processing (such as closing file descriptors or calls to the static destructor functions) is done, and any `atexit' functions are not called; only the hardware interrupt handlers are unhooked, to prevent system crashes e.g. after a call to `abort'. This function is normally called only by `exit' and `abort'. Return Value ------------ This function does not return. Portability ----------- not ANSI, not POSIX File: libc.info, Node: exit, Next: exp, Prev: _exit, Up: Alphabetical List exit ==== Syntax ------ #include <stdlib.h> void exit(int exit_code); Description ----------- This function exits the program, returning EXIT_CODE to the calling process. Before exiting, all open files are closed and all `atexit' and `on_exit' requests are processed. Return Value ------------ This function does not return. Portability ----------- ANSI, POSIX Example ------- if (argc < 4) { print_usage(); exit(1); } File: libc.info, Node: exp, Next: exp10, Prev: exit, Up: Alphabetical List exp === Syntax ------ #include <math.h> double exp(double x); Description ----------- This function computes the exponential of X, e^x, where e is the base of the natural system of logarithms, approximately 2.718281828. Return Value ------------ e to the X power. If the value of X is finite, but so large in magnitude that its exponential cannot be accurately represented by a `double', the return value is the nearest representable `double' (possibly, an `Inf'), and `errno' is set to `ERANGE'. If X is either a positive or a negative infinity, the result is either `+Inf' or zero, respectively, and `errno' is not changed. If X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: exp10, Next: exp2, Prev: exp, Up: Alphabetical List exp10 ===== Syntax ------ #include <math.h> double exp10(double x); Description ----------- This function computes 10 to the power of X, 10^x. Return Value ------------ 10 to the X power. If the value of X is finite, but so large in magnitude that 10^x cannot be accurately represented by a `double', the return value is the nearest representable `double' (possibly, an `Inf'), and `errno' is set to `ERANGE'. If X is either a positive or a negative infinity, the result is either `+Inf' or zero, respectively, and `errno' is not changed. If X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: exp2, Next: expm1, Prev: exp10, Up: Alphabetical List exp2 ==== Syntax ------ #include <math.h> double exp2(double x); Description ----------- This function computes 2 to the power of X, 2^x. Return Value ------------ 2 to the X power. If the value of X is finite, but so large in magnitude that 2^x cannot be accurately represented by a `double', the return value is is the nearest representable `double' (possibly, an `Inf'), and `errno' is set to `ERANGE'. If X is either a positive or a negative infinity, the result is either `+Inf' or zero, respectively, and `errno' is not changed. If X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: expm1, Next: fabs, Prev: exp2, Up: Alphabetical List expm1 ===== Syntax ------ #include <math.h> double expm1(double x); Description ----------- This function computes the value of e^x - 1, the exponential of X minus 1, where e is the base of the natural system of logarithms, approximately 2.718281828. The result is more accurate than `exp(x) - 1' for small values of X, where the latter method would lose many significant digits. Return Value ------------ e raised to the power X, minus 1. If the value of X is finite, but so large that its exponent would overflow a `double', the return value is `Inf', and `errno' is set to `ERANGE'. If X is either a positive or a negative infinity, the result is either `+Inf' or -1, respectively, and `errno' is not changed. If X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: fabs, Next: _far*, Prev: expm1, Up: Alphabetical List fabs ==== Syntax ------ #include <math.h> double fabs(double x); Description ----------- This function computes the absolute value of its argument X. Return Value ------------ X if X is positive, else -X. Note that in this context, +0.0 is positive and -0.0 is negative. Infinities and `NaN's are returned unchanged, except for the sign. Portability ----------- ANSI, POSIX File: libc.info, Node: _far*, Next: fclose, Prev: fabs, Up: Alphabetical List _far* ===== Syntax ------ #include <sys/farptr.h> unsigned char _farpeekb(unsigned short selector, unsigned long offset); unsigned short _farpeekw(unsigned short selector, unsigned long offset); unsigned long _farpeekl(unsigned short selector, unsigned long offset); void _farpokeb(unsigned short sel, unsigned long off, unsigned char val); void _farpokew(unsigned short sel, unsigned long off, unsigned short val); void _farpokel(unsigned short sel, unsigned long off, unsigned long val); void _farsetsel(unsigned short selector); unsigned short _fargetsel(void); void _farnspokeb(unsigned long offset, unsigned char value); void _farnspokew(unsigned long offset, unsigned short value); void _farnspokel(unsigned long offset, unsigned long value); unsigned char _farnspeekb(unsigned long offset); unsigned short _farnspeekw(unsigned long offset); unsigned long _farnspeekl(unsigned long offset); Description ----------- These functions provide the equivalent functionality of "far pointers" to peek or poke an absolute memory addresses, even though gcc doesn't understand the keyword "far". They come in handy when you need to access memory-mapped devices (like VGA) or some address in lower memory returned by a real-mode service. These functions are provided as inline assembler functions, so when you optimize your program they reduce to only a few opcodes (only one more than a regular memory access), resulting in very optimal code. The first two groups of functions take a SELECTOR and an OFFSET. This selector is *not* a dos segment. If you want to access dos memory, pass _go32_info_block.selector_for_linear_memory (or just _dos_ds) as the selector, and seg*16+ofs as the offset. For functions which poke the memory, you should also provide the VALUE to put there. The last two groups assume that you've used `_farsetsel' to specify the selector. You should avoid making any function calls between `_farsetsel' and using these other functions, unless you're absolutely sure that they won't modify that selector. This allows you to optimize loops by setting the selector once outside the loop, and using the shorter functions within the loop. You can use `_fargetsel' if you want to temporary change the selector with `_farsetsel' and restore it afterwards. Return Value ------------ Functions which peek the address return the value at given address. `_fargetsel' returns the current selector. Portability ----------- not ANSI, not POSIX File: libc.info, Node: fclose, Next: fcntl, Prev: _far*, Up: Alphabetical List fclose ====== Syntax ------ #include <stdio.h> int fclose(FILE *file); Description ----------- This function closes the given FILE. Return Value ------------ Zero on success, else `EOF'. Portability ----------- ANSI, POSIX Example ------- FILE *f = fopen("data", "r"); fprintf(f, "Hello\n"); fclose(f); File: libc.info, Node: fcntl, Next: fcvt, Prev: fclose, Up: Alphabetical List fcntl ===== Syntax ------ #include <fcntl.h> int fcntl (int fd, int cmd, ...); Description ----------- This function performs the operation specified by CMD on the file open on handle FD. The following operations are defined by the header `fcntl.h': `F_DUPFD' Returns a file handle that duplicates FD like `dup' does (*note dup::.), except that `fcntl' also makes sure the returned handle is the lowest available handle greater than or equal to the integer value of the third argument. `F_GETFD' Get the `FD_CLOEXEC' close-on-exec (a.k.a. no-inherit) status of FD. If the returned value has its least-significant bit set, the file will not be inherited by programs invoked by this process; otherwise, the file will remain open in the child processes. Note that only the first 20 handles can be passed to child processes by DOS/Windows; handles beyond that cannot be inherited. In addition, the stub loader of the child DJGPP program will forcibly close handles 19 and 18 (since otherwise it will be unable to read the COFF executable information and enter protected mode). Therefore, the current implementation always returns 0 for handles below 18, meaning that all those handles are inherited, and `FD_CLOEXEC' for handles 18 and above. The no-inherit bit can be set when the file is open, by using the `O_NOINHERIT' in the open flags; see *Note open::. `F_SETFD' Set the close-on-exec flag for the handle FD using the LSB of the integer value supplied as the third argument. Currently, `fcntl' always fails this call and sets `errno' to `ENOSYS', since DOS/Windows don't support changing the no-inherit status of an open file. `F_GETFL' Get the open mode and status flags associated with the handle FD. The flags are those supported by `open' and `creat' functions, like `O_READONLY', `O_APPEND', etc. Currently, this command always returns zero, with no flags set. `F_SETFL' Set the open mode and status flags associated with the handle FD. This always fails and sets `errno' to `ENOSYS', since DOS and Windows don't allow to change the descriptor flags after the file is open. `F_GETLK' Get a description of a file segment lock as specified in the structure pointed to by the third argument. This is unsupported and will always fail. `F_SETLK' Set or clear a file segment lock according to the structure pointed to by the third argument. This is unsupported and will always fail. `F_SETLKW' Same as `F_SETLK', but if the lock is blocked, the call will wait until it is unblocked and the lock can be applied. This is unsupported and will always fail. This function can be hooked by the "Filesystem extensions", see *Note File System Extensions::. If you don't want this, and you are calling `fcntl' with the `F_DUPFD' command, you should use `dup2' instead, see *Note dup2::. Return Value ------------ If an invalid or unsupported value is passed in CMD, or FD is an invalid file handle, the function returns -1 and sets `errno' to the appropriate value. Unsupported values of CMD cause `ENOSYS' to be stored in `errno'. If CMD is `F_DUPFD', the function returns the new descriptor or -1 in case of a failure. Portability ----------- not ANSI, POSIX (see note 1) Notes: 1. Contrary to Posix requirement, the handle returned by `F_DUPFD' shares the `FD_CLOEXEC' flag with FD (unless they are on different sides of the 20-handle mark), since DOS/Windows only maintain a single set of bits for all the handles associated with the same call to `open'. Example ------- /* Save the handle in a way that it won't be passed to child processes. */ int saved_fd = fcntl (fd, F_DUPFD, 20); File: libc.info, Node: fcvt, Next: fcvtbuf, Prev: fcntl, Up: Alphabetical List fcvt ==== Syntax ------ #include <stdlib.h> char * fcvt (double value, int ndigits, int *decpt, int *sign) Description ----------- This function converts the VALUE into a null-terminated string, and returns a pointer to that string. `fcvt' works exactly like `fcvtbuf' (*note fcvtbuf::.), except that it generates the string in an internal static buffer which is overwritten on each call. Return Value ------------ A pointer to the generated string. Portability ----------- not ANSI, not POSIX File: libc.info, Node: fcvtbuf, Next: fdopen, Prev: fcvt, Up: Alphabetical List fcvtbuf ======= Syntax ------ #include <stdlib.h> char * fcvtbuf (double value, int ndigits, int *decpt, int *sign, char *buf) Description ----------- This function converts its argument VALUE into a null-terminated string in BUF with NDIGITS digits *to the right* of the decimal point. NDIGITS can be negative to indicate rounding to the left of the decimal point. BUF should have enough space to hold at least `310+max(0,NDIGITS)' characters. Note that, unlike `ecvtbuf' (*note ecvtbuf::.), `fcvtbuf' only counts the digits *to the right* of the decimal point. Thus, if VALUE is 123.45678 and NDIGITS is 4, then `ecvtbuf' will produce "1235", but `fcvtbuf' will produce "1234568" (and *DECPT will be 3 in both cases). The produced string in BUF does *not* include the decimal point. Instead, the position of the decimal point relative to the beginning of BUF is stored in an integer variable whose address is passed in DECPT. Thus, if BUF is returned as "1234" and *DECPT as 1, this corresponds to a value of 1.234; if *DECPT is -1, this corresponds to a value of 0.01234, etc. The sign is also not included in BUF's value. If VALUE is negative, `ecvtbuf' puts a nonzero value into the variable whose address is passed in SIGN; otherwise it stores zero in *SIGN. The least-significant digit in BUF is rounded. `ecvtbuf' produces the string "NaN" if VALUE is a NaN, and "Inf" or "Infinity" if VALUE is an infinity (the longer form is produced when NDIGITS is 8 or more). Return Value ------------ A pointer to BUF. Portability ----------- not ANSI, not POSIX Example ------- #include <stdlib.h> #include <stdio.h> #include <math.h> char vbuf[20]; int fsign, fdecpt; fcvtbuf (M_PI, 5, &fdecpt, &fsign, buf) /* This will print " 314159". */ printf ("%c%s", fsign ? '-' : ' ', buf); File: libc.info, Node: fdopen, Next: feof, Prev: fcvtbuf, Up: Alphabetical List fdopen ====== Syntax ------ #include <stdio.h> FILE *fdopen(int fd, const char *mode); Description ----------- This function opens a stream-type file that uses the given FD file, which must already be open. The file is opened with the modes specified by MODE, which is the same as for `fopen'. *Note fopen::. Return Value ------------ The newly created `FILE *', or `NULL' on error. Portability ----------- not ANSI, POSIX Example ------- FILE *stdprn = fdopen(4, "w"); File: libc.info, Node: feof, Next: ferror, Prev: fdopen, Up: Alphabetical List feof ==== Syntax ------ #include <stdio.h> int feof(FILE *file); Description ----------- This function can be used to indicate if the given FILE is at the end-of-file or not. Return Value ------------ Nonzero at end-of-file, zero otherwise. Portability ----------- ANSI, POSIX Example ------- while (!feof(stdin)) gets(line); File: libc.info, Node: ferror, Next: fflush, Prev: feof, Up: Alphabetical List ferror ====== Syntax ------ #include <stdio.h> int ferror(FILE *file); Description ----------- This function can be used to indicate if the given FILE has encountered an error or not. *Note clearerr::. Return Value ------------ Nonzero for an error, zero otherwize. Portability ----------- ANSI, POSIX Example ------- if (ferror(stdin)) exit(1); File: libc.info, Node: fflush, Next: ffs, Prev: ferror, Up: Alphabetical List fflush ====== Syntax ------ #include <stdio.h> int fflush(FILE *file); Description ----------- If FILE is not a `NULL' pointer, this function causes any unwritten buffered data to be written out to the given FILE. This is useful in cases where the output is line buffered and you want to write a partial line. If FILE is a `NULL' pointer, `fflush' writes any buffered output to all files opened for output. Note that `fflush' has no effect for streams opened for reading only. Also note that the operating system can further buffer/cache writes to disk files; a call to `fsync' (*note fsync::.) or `sync' (*note sync::.) is typically required to actually deliver data to the file(s). Return Value ------------ Zero on success, -1 on error. When called with a `NULL' pointer, -1 will be returned if an error happened while flushing some of the streams (but `fflush' will still try to flush all the rest before it returns). Portability ----------- ANSI, POSIX Example ------- printf("Enter value : "); fflush(stdout); scanf(result); File: libc.info, Node: ffs, Next: fgetc, Prev: fflush, Up: Alphabetical List ffs === Syntax ------ #include <string.h> int ffs(int _mask); Description ----------- This function find the first (least significant) bit set in the input value. Return Value ------------ Bit position (1..32) of the least significant set bit, or zero if the input value is zero. Portability ----------- not ANSI, not POSIX Example ------- ffs(0) = 0 ffs(1) = 1 ffs(5) = 1 ffs(96) = 6 File: libc.info, Node: fgetc, Next: fgetgrent, Prev: ffs, Up: Alphabetical List fgetc ===== Syntax ------ #include <stdio.h> int fgetc(FILE *file); Description ----------- Returns the next character in the given FILE as an unsigned char. Return Value ------------ The given char (value 0..255) or `EOF' at end-of-file. Portability ----------- ANSI, POSIX Example ------- int c; while((c=fgetc(stdin)) != EOF) fputc(c, stdout); File: libc.info, Node: fgetgrent, Next: fgetpos, Prev: fgetc, Up: Alphabetical List fgetgrent ========= Syntax ------ #include <grp.h> struct group *fgetgrent(FILE *file); Description ----------- This function, in MS-DOS, is exactly the same as `getgrent' (*note getgrent::.). Portability ----------- not ANSI, not POSIX File: libc.info, Node: fgetpos, Next: fgets, Prev: fgetgrent, Up: Alphabetical List fgetpos ======= Syntax ------ #include <stdio.h> int fgetpos(FILE *file, fpos_t *offset); Description ----------- This function records the current file pointer for FILE, for later use by `fsetpos'. *Note fsetpos::. *Note ftell::. Return Value ------------ Zero if successful, nonzero if not. Portability ----------- ANSI, POSIX File: libc.info, Node: fgets, Next: File System Extensions, Prev: fgetpos, Up: Alphabetical List fgets ===== Syntax ------ #include <stdio.h> char *fgets(char *buffer, int maxlength, FILE *file); Description ----------- This function reads as much of a line from a file as possible, stopping when the buffer is full (MAXLENGTH-1 characters), an end-of-line is detected, or `EOF' or an error is detected. It then stores a `NULL' to terminate the string. Return Value ------------ The address of the buffer is returned on success, if `EOF' is encountered before any characters are stored, or if an error is detected, `NULL' is returned instead. Portability ----------- ANSI, POSIX Example ------- char buf[100]; while (fgets(buf, 100, stdin)) fputs(buf, stdout); File: libc.info, Node: File System Extensions, Next: __file_exists, Prev: fgets, Up: Alphabetical List File System Extensions ====================== Description ----------- The File System Extensions are a part of the lowest level of I/O operations in the C runtime library of DJGPP. These extensions are provided to allow for cases where Unix uses a file descriptor to access such items as serial ports, memory, and the network, but DOS does not. It allows a set of functions (called an extension) to gain control when one of these low-level functions is called on a file descriptor set up by the extension. Each extension must provide one or two handler functions. All handler functions take the same arguments: int function(__FSEXT_Fnumber func_number, int *rv, va_list args); The FUNC_NUMBER identifies which function is to be emulated. The file `<sys/fsext.h>' defines the function numbers as follows: `__FSEXT_nop' A no-op. This is currently unused by the library functions. `__FSEXT_open' An open handler. This is called just before the library is about to issue the DOS OpenFile call on behalf of your program. `__FSEXT_creat' A create handler. Called when a file needs to be created. Note that the handler should both create the "file" and open it. `__FSEXT_read' A read handler. Called when data should be read from a "file". `__FSEXT_write' A write handler. Called to write data to a "file". On "text" files it receives the ORIGINAL (unconverted) buffer. `__FSEXT_ready' A ready handler. It is called by `select' library function (*note select::.) when it needs to know whether a handle used to reference the "file" is ready for reading or writing, or has an error condition set. The handler should return an OR'ed bit mask of the following bits (defined on `<sys/fsext.h>'): `__FSEXT_ready_read' The "file" is ready for reading. `__FSEXT_ready_write' The "file" is ready for writing. `__FSEXT_ready_error' The "file" has an error condition set. `__FSEXT_close' A close handler. Called when the "file" should be closed. `__FSEXT_fcntl' A file fcntl handler. `__FSEXT_ioctl' A file ioctl handler. `__FSEXT_lseek' A file lseek handler (*note lseek::.). `__FSEXT_link' A file link handler (*note link::.). This is most relevant to file system extensions that emulate a directory structure. `__FSEXT_unlink' A file unlink handler (*note unlink::.). This is most relevant to file system extensions that emulate a directory structure. `__FSEXT_dup' A file dup handler (*note dup::.). This is called when a new descriptor is needed to refer to an existing descriptor. `__FSEXT_dup2' A file dup2 handler (*note dup2::.). This is called when two different file descriptors are used to refer to the same open file. `__FSEXT_fstat' A file fstat handler (*note fstat::.). The extension should fill in various status information about the emulated file. RV points to a temporary return value pointer. If the function is emulated by the handler, the return value should be stored here, and the handler should return a nonzero value. If the handler returns zero, it is assumed to have not emulated the call, and the regular DOS I/O function will happen. The ARGS represent the arguments passed to the original function; these point to the actual arguments on the stack, so the emulation may choose to modify them and return zero to the regular function, which will then act on the modified arguments. A normal extension would provide these parts: * Some function to create a connection to the extension. This may be a custom function (such as `socket' for networking) or an extension to open (such as `/dev/ttyS0' to access the serial port). * Initialization code that adds the open handler, if any. * Overrides for the basic I/O functions, such as `read' and `write'. This is a single function in the extension that uses the function number parameter to select an extension function. * The core functionality of the extension, if any. Please note that the special Unix filenames `/dev/null' and `/dev/tty' are already mapped to the appropriate DOS names `NUL' and `CON', respectively, so you don't need to write extensions for these. File: libc.info, Node: __file_exists, Next: __file_tree_walk, Prev: File System Extensions, Up: Alphabetical List __file_exists ============= Syntax ------ #include <unistd.h> int __file_exists(const char *_fn); Description ----------- This function provides a fast way to ask if a given file exists. Unlike access(), this function does not cause other objects to get linked in with your program, so is used primarily by the startup code to keep minimum code size small. Return Value ------------ Zero if the file does not exist, nonzero if it does. Note that this is the opposite of what access() returns. Portability ----------- not ANSI, not POSIX Example ------- if (__file_exists(fname)) process_file(fname); File: libc.info, Node: __file_tree_walk, Next: filelength, Prev: __file_exists, Up: Alphabetical List __file_tree_walk ================ Syntax ------ #include <dir.h> int __file_tree_walk(const char *dir, int (*func)(const char *path, const struct ffblk *ff)); Description ----------- This function recursively descends the directory hierarchy which starts with DIR. For each file in the hierarchy, `__file_tree_walk' calls the user-defined function FUNC which is passed a pointer to a `NULL'-terminated character array in PATH holding the full pathname of the file, a pointer to a `ffblk' structure (*note findfirst::.) FF with a DOS filesystem information about that file. This function always visits a directory before any of its siblings. The argument DIR must be a directory, or `__file_tree_walk' will fail and set ERRNO to `ENOTDIR'. The directory DIR itself is never passed to FUNC. The tree traversal continues until one of the following events: (1) The tree is exhausted (i.e., all descendants of DIR are processed). In this case, `__file_tree_walk' returns 0, meaning a success. (2) An invocation of FUNC returns a non-zero value. In this case, `__file_tree_walk' stops the tree traversal and returns whatever FUNC returned. (3) An error is detected within `__file_tree_walk'. In that case, `ftw' returns -1 and sets ERRNO (*note errno::.) to a suitable value. Return Value ------------ Zero in case the entire tree was successfully traversed, -1 if `__file_tree_walk' detected some error during its operation, or any other non-zero value which was returned by the user-defined function FUNC. Portability ----------- not ANSI, not POSIX Example ------- #include <stdlib.h> int ff_walker(const char *path, const struct ffblk *ff) { printf("%s:\t%lu\t", path, ff->ff_fsize); if (ff->ff_attrib & 1) printf("R"); if (ff->ff_attrib & 2) printf("H"); if (ff->ff_attrib & 4) printf("S"); if (ff->ff_attrib & 8) printf("V"); if (ff->ff_attrib & 0x10) printf("D"); if (ff->ff_attrib & 0x20) printf("A"); printf("\n"); if (strcmp(ff->ff_name, "XXXXX") == 0) return 42; return 0; } int main(int argc, char *argv[]) { if (argc > 1) { char msg[80]; sprintf(msg, "__file_tree_walk: %d", __file_tree_walk(argv[1], ff_walker)); if (errno) perror(msg); else puts(msg); } else printf("Usage: %s dir\n", argv[0]); return 0; } File: libc.info, Node: filelength, Next: fileno, Prev: __file_tree_walk, Up: Alphabetical List filelength ========== Syntax ------ #include <io.h> long filelength(int fhandle); Description ----------- This function returns the size, in bytes, of a file whose handle is specified in the argument FHANDLE. To get the handle of a file opened by *Note fopen:: or *Note freopen::, you can use *Note fileno:: macro. Return Value ------------ The size of the file in bytes, or (if any error occured) -1L and ERRNO set to a value describing the cause of the failure. Portability ----------- not ANSI, not POSIX Example ------- printf("Size of file to which STDIN is redirected is %ld\n", filelength(0)); File: libc.info, Node: fileno, Next: findfirst, Prev: filelength, Up: Alphabetical List fileno ====== Syntax ------ #include <stdio.h> int fileno(FILE *file); Description ----------- This function returns the raw file descriptor number that FILE uses for I/O. Return Value ------------ The file descriptor number. Portability ----------- not ANSI, POSIX File: libc.info, Node: findfirst, Next: findnext, Prev: fileno, Up: Alphabetical List findfirst ========= Syntax ------ #include <dir.h> int findfirst(const char *pathname, struct ffblk *ffblk, int attrib); Description ----------- This function and the related `findnext' (*note findnext::.) are used to scan directories for the list of files therein. The PATHNAME is a wildcard that specifies the directory and files to search for (such as `subdir/*.c'), FFBLK is a structure to hold the results and state of the search, and ATTRIB is a combination of the following: `FA_RDONLY' Include read-only files in the search (Ignored.) `FA_HIDDEN' Include hidden files in the search `FA_SYSTEM' Include system files in the search `FA_LABEL' Include the volume label in the search `FA_DIREC' Include subdirectories in the search `FA_ARCH' Include modified files in the search (Ignored.) If a file has flag bits that are not specified in the ATTRIB parameter, the file will be excluded from the results. Thus, if you specified `FA_DIREC' and `FA_LABEL', subdirectories and the volume label will be included in the results. Hidden and system files will be excluded. Since `findfirst' calls DOS function 4eh, it is not possible to exclude read-only files or archive files from the results. Even if the FA_ARCH and FA_RDONLY bits are not specified in the attrib parameter, the results will include any read-only and archive files in the directory searched. This function supports long file names. The results of the search are stored in FFBLK, which is extended when the LFN API (*note LFN: _use_lfn.) is supported. Fields marked LFN are only valid if the `lfn_magic' member is set to "LFN32". struct ffblk { char lfn_magic[6]; /* LFN: the magic "LFN32" signature */ short lfn_handle; /* LFN: the handle used by findfirst/findnext */ unsigned short lfn_ctime; /* LFN: file creation time */ unsigned short lfn_cdate; /* LFN: file creation date */ unsigned short lfn_atime; /* LFN: file last access time (usually 0) */ unsigned short lfn_adate; /* LFN: file last access date */ char ff_reserved[5]; /* used to hold the state of the search */ unsigned char ff_attrib; /* actual attributes of the file found */ unsigned short ff_ftime; /* hours:5, minutes:6, (seconds/2):5 */ unsigned short ff_fdate; /* (year-1980):7, month:4, day:5 */ unsigned long ff_fsize; /* size of file */ char ff_name[260]; /* name of file as ASCIIZ string */ } Return Value ------------ Zero if a match is found, nonzero if none found. Portability ----------- not ANSI, not POSIX Example ------- struct ffblk f; int done = findfirst("*.exe", &f, FA_HIDDEN | FA_SYSTEM); while (!done) { printf("%10u %2u:%02u:%02u %2u/%02u/%4u %s\n", f.ff_fsize, (f.ff_ftime >> 11) & 0x1f, (f.ff_ftime >> 5) & 0x3f, (f.ff_ftime & 0x1f) * 2, (f.ff_fdate >> 5) & 0x0f, (f.ff_fdate & 0x1f), ((f.ff_fdate >> 9) & 0x7f) + 1980, f.ff_name); done = findnext(&f); } File: libc.info, Node: findnext, Next: _fixpath, Prev: findfirst, Up: Alphabetical List findnext ======== Syntax ------ #include <dir.h> int findnext(struct ffblk *ffblk); Description ----------- This finds the next file in the search started by `findfirst'. *Note findfirst::. Return Value ------------ Zero if there was a match, else nonzero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _fixpath, Next: floor, Prev: findnext, Up: Alphabetical List _fixpath ======== Syntax ------ #include <sys/stat.h> void _fixpath(const char *in_path, char *out_path); Description ----------- This function canonicalizes the input path IN_PATH and stores the result in the buffer pointed to by OUT_PATH. The path is fixed by removing consecutive and trailing slashes, making the path absolute if it's relative by prepending the current drive letter and working directory, removing "." components, collapsing ".." components, adding a drive specifier if needed, and converting all slashes to '/'. DOS-style 8+3 names of directories which are part of the pathname, as well as its final filename part, are returned lower-cased in OUT_PATH, but long filenames are left intact. *Note _preserve_fncase::, for more details on letter-case conversions in filenames. Since the returned path name can be longer than the original one, the caller should ensure there is enough space in the buffer pointed to by OUT_PATH. Using ANSI-standard constant `FILENAME_MAX' (defined on `stdio.h') or Posix-standard constant `PATH_MAX' (defined on `limits.h') is recommended. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- char oldpath[100], newpath[FILENAME_MAX]; scanf(oldpath); _fixpath(oldpath, newpath); printf("that really is %s\n", newpath); File: libc.info, Node: floor, Next: _flush_disk_cache, Prev: _fixpath, Up: Alphabetical List floor ===== Syntax ------ #include <math.h> double floor(double x); Description ----------- This function computes the largest integer not greater than X. Return Value ------------ The largest integer value less than or equal to X. Infinities and `NaN's are returned unchanged. Portability ----------- ANSI, POSIX File: libc.info, Node: _flush_disk_cache, Next: fmod, Prev: floor, Up: Alphabetical List _flush_disk_cache ================= Syntax ------ #include <io.h> void _flush_disk_cache (void); Description ----------- Attempts to update the disk with the data cached in the write-behind disk caches (such as `SmartDrv' and the built-in Windows 95 disk cache). Note that this does *not* flushes the DOS buffers. You need to call `fsync' (*note fsync::.) or `close' (*note close::.) to force DOS to commit the file data to the disk; `sync' (*note sync::.) does that for all open files. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- /* Make sure all files are actually written to disk. */ sync (); _flush_disk_cache (); File: libc.info, Node: fmod, Next: _fmode, Prev: _flush_disk_cache, Up: Alphabetical List fmod ==== Syntax ------ #include <math.h> double fmod(double x, double y); Description ----------- This function computes the remainder of `X/Y', which is X - iY for some integer i such that iY < X < (i+1)Y. Return Value ------------ The remainder of X/Y. If X is `Inf' or `NaN', the return value is `NaN' and `errno' is set to `EDOM'. If Y is zero, the return value is zero (but `errno' is not changed). Portability ----------- ANSI, POSIX File: libc.info, Node: _fmode, Next: fnmatch, Prev: fmod, Up: Alphabetical List _fmode ====== Syntax ------ #include <fcntl.h> extern int _fmode; Description ----------- This variable may be set to `O_TEXT' or `O_BINARY' to specify the mode that newly opened files should be opened in if the open call did not specify. *Note open::. *Note fopen::. The default value is `O_TEXT'. Portability ----------- not ANSI, not POSIX Example ------- _fmode = O_BINARY; File: libc.info, Node: fnmatch, Next: fnmerge, Prev: _fmode, Up: Alphabetical List fnmatch ======= Syntax ------ #include <fnmatch.h> int fnmatch(const char *pattern, const char *string, int flags); Description ----------- This function indicates if STRING matches the PATTERN. The PATTERN may include the following special characters: `*' Matches zero of more characters. `?' Matches exactly one character. `[...]' Matches one character if it's in a range of characters. If the first character is `!', matches if the character is not in the range. Between the brackets, the range is specified by listing the characters that are in the range, or two characters separated by `-' to indicate all characters in that range. For example, `[a-d]' matches `a', `b', `c', or `d'. If you want to include the literal `-' in the range, make it the first character, like in `[-afz]'. `\' Causes the next character to not be treated as a wildcard. For example, `\*' matches an asterisk. This feature is not available if FLAGS includes `FNM_NOESCAPE', in which case `\' is treated as a directory separator. The value of FLAGS is a combination of zero of more of the following: `FNM_PATHNAME' This means that the STRING should be treated as a pathname, in that the slash characters `/' and `\' in STRING never match any of the wildcards in PATTERN. `FNM_NOESCAPE' If this flag is *not* set, the backslash `\' may be used in PATTERN for quoting special characters. If this flag *is* set, `\' is treated as a directory separator. `FNM_NOCASE' If this flag is set, `fnmatch' matches characters case-insensitively, including in character ranges like `[a-f]'. Note that the case-folding is done by calling `toupper' (*note toupper::.), and thus might be sensitive to the current locale. `FNM_PERIOD' This flag is accepted and ignored in the current implementation. (This is the right thing to do on non-LFN platforms, where leading dots in file names are forbidden.) In the Posix specification, if this flag is set, leading dots in file names will not match any wildcards. If `FNM_PATHNAME' is set, a dot after a slash also doesn't match any wildcards. The DJGPP implementation treats forward slashes and backslashes as equal when `FNM_NOESCAPE' is set, since on DOS/Windows these two characters are both used as directory separators in file names. Return Value ------------ Zero if the string matches, `FNM_NOMATCH' if it does not. Posix defines an additional `FNM_ERROR' code that's returned in case of an error, but the current implementation never returns it. Portability ----------- not ANSI, POSIX (see note 1) Notes: 1. The equal handling of `\' and `/' is DJGPP-specific. Example ------- if (fnmatch("*.[ch]", filename, FNM_PATHNAME|FNM_NOCASE)) do_source_file(filename); File: libc.info, Node: fnmerge, Next: fnsplit, Prev: fnmatch, Up: Alphabetical List fnmerge ======= Syntax ------ #include <dir.h> void fnmerge (char *path, const char *drive, const char *dir, const char *name, const char *ext); Description ----------- This function constructs a file PATH from its components DRIVE, DIR, NAME, and EXT. If any of these is a `NULL' pointer, it won't be used. Usually, the DRIVE string should include the trailing colon ``:'', the DIR string should include the trailing slash ``/'' or backslash ``\'', and the EXT string should include the leading dot ``.''. However, if any of these isn't present, `fnmerge' will add them. *Note fnsplit::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- char buf[MAXPATH]; fnmerge(buf, "d:", "/foo/", "data", ".txt"); File: libc.info, Node: fnsplit, Next: fopen, Prev: fnmerge, Up: Alphabetical List fnsplit ======= Syntax ------ #include <dir.h> int fnsplit (const char *path, char *drive, char *dir, char *name, char *ext); Description ----------- This function decomposes a PATH into its components. It is smart enough to know that `.' and `..' are directories, and that file names with a leading dot, like `.emacs', are not all extensions. The DRIVE, DIR, NAME and EXT arguments should all be passed, but some or even all of them might be `NULL' pointers. Those of them which are non-`NULL' should point to buffers which have enough room for the strings they would hold. The constants `MAXDRIVE', `MAXDIR', `MAXFILE' and `MAXEXT', defined on dir.h, define the maximum length of these buffers. *Note fnmerge::. Return Value ------------ A flag that indicates which components were found: `DRIVE' The drive letter was found. `DIRECTORY' A directory or subdirectories was found. `FILENAME' A filename was found. `EXTENSION' An extension was found. `WILDCARDS' The path included `*' or `?'. Portability ----------- not ANSI, not POSIX Example ------- char d[MAXDRIVE], p[MAXDIR], f[MAXFILE], e[MAXEXT]; int which = fnsplit("d:/djgpp/bin/gcc.exe", d, p, f, e); d = "d:" p = "/djgpp/bin/" f = "gcc" e = ".exe" File: libc.info, Node: fopen, Next: fork, Prev: fnsplit, Up: Alphabetical List fopen ===== Syntax ------ #include <stdio.h> FILE *fopen(const char *filename, const char *mode); Description ----------- This function opens a stream corresponding to the named FILENAME with the given MODE. The mode can be one of the following: `r' Open an existing file for reading. `w' Create a new file (or truncate an existing file) and open it for writing. `a' Open an existing file (or create a new one) for writing. The file pointer is positioned to the end of the file before every write. Followed by any of these characters: `b' Force the file to be open in binary mode instead of the default mode. When called to open the console in binary mode, `fopen' will disable the generation of `SIGINT' when you press `Ctrl-C' (`Ctrl-Break' will still cause `SIGINT'), because many programs that use binary reads from the console will also want to get the `^C' characters. You can use the `__djgpp_set_ctrl_c' library function (*note __djgpp_set_ctrl_c::.) if you want `Ctrl-C' to generate interrupts while console is read in binary mode. `t' Force the file to be open in text mode instead of the default mode. `+' Open the file as with `O_RDWR' so that both reads and writes can be done to the same file. If the file is open for both reading and writing, you must call `fflush', `fseek', or `rewind' before switching from read to write or from write to read. The open file is set to line buffered if the underlying object is a device (stdin, stdout, etc), or is fully buffered if the underlying object is a disk file (data.c, etc). If `b' or `t' is not specified in MODE, the file type is chosen by the value of `fmode' (*note _fmode::.). If you need to specify the DOS share flags use the `__djgpp_share_flags'. *Note __djgpp_share_flags::. Return Value ------------ A pointer to the `FILE' object, or `NULL' if there was an error. Portability ----------- ANSI, POSIX Example ------- FILE *f = fopen("foo", "rb+"); /* open existing file for read/write, binary mode */ File: libc.info, Node: fork, Next: fpathconf, Prev: fopen, Up: Alphabetical List fork ==== Syntax ------ #include <unistd.h> pid_t fork(void); Description ----------- This function always returns -1 and sets `errno' to ENOMEM, as MS-DOS does not support multiple processes. It exists only to assist in porting Unix programs. Portability ----------- not ANSI, POSIX File: libc.info, Node: fpathconf, Next: _fpreset, Prev: fork, Up: Alphabetical List fpathconf ========= Syntax ------ #include <unistd.h> long fpathconf(int fd, int name); Description ----------- Returns configuration information on the filesystem that the open file resides on. *Note pathconf::. If the filesystem cannot be determined from the file handle FD (e.g., for character devices), `fpathconf' will return the info for the current drive. Return Value ------------ The configuration value; for details, see *Note pathconf::. Portability ----------- not ANSI, POSIX File: libc.info, Node: _fpreset, Next: fprintf, Prev: fpathconf, Up: Alphabetical List _fpreset ======== Syntax ------ #include <float.h> void _fpreset(void); Description ----------- Resets the FPU completely. Portability ----------- not ANSI, not POSIX File: libc.info, Node: fprintf, Next: fpurge, Prev: _fpreset, Up: Alphabetical List fprintf ======= Syntax ------ #include <stdio.h> int fprintf(FILE *file, const char *format, ...); Description ----------- Prints formatted output to the named file. *Note printf::. Return Value ------------ The number of characters written. Portability ----------- ANSI, POSIX File: libc.info, Node: fpurge, Next: fputc, Prev: fprintf, Up: Alphabetical List fpurge ====== Syntax ------ #include <stdio.h> int fpurge(FILE *file); Description ----------- If FILE designates a buffered stream open for writing or for both reading and writing, this function purges the stream's buffer without writing it to disk. Otherwise, it does nothing (so it has no effect on read-only streams such as `stdin'). Return Value ------------ Zero on success, -1 on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: fputc, Next: fputs, Prev: fpurge, Up: Alphabetical List fputc ===== Syntax ------ #include <stdio.h> int fputc(int character, FILE *file); Description ----------- This function writes the given CHARACTER to the given `file'. Return Value ------------ The given character [0..255] or `EOF'. Portability ----------- ANSI, POSIX Example ------- fputc('\n', stdout); File: libc.info, Node: fputs, Next: fread, Prev: fputc, Up: Alphabetical List fputs ===== Syntax ------ #include <stdio.h> int fputs(const char *string, FILE *file); Description ----------- This function all the characters of STRING (except the trailing `NULL') to the given FILE. Return Value ------------ A nonnegative number on success, `EOF' on error. Portability ----------- ANSI, POSIX Example ------- fputs("Hello\n", stdout); File: libc.info, Node: fread, Next: free, Prev: fputs, Up: Alphabetical List fread ===== Syntax ------ #include <stdio.h> size_t fread(void *buffer, size_t size, size_t number, FILE *file); Description ----------- This function reads SIZE*NUMBER characters from FILE to BUFFER. Return Value ------------ The number of items of size SIZE read, or less if there was an error. Portability ----------- ANSI, POSIX Example ------- int foo[10]; fread(foo, sizeof(int), 10, stdin); File: libc.info, Node: free, Next: freopen, Prev: fread, Up: Alphabetical List free ==== Syntax ------ #include <stdlib.h> void free(void *ptr); Description ----------- Returns the allocated memory to the heap (*note malloc::.). If the PTR is `NULL', it does nothing. Return Value ------------ None. Portability ----------- ANSI, POSIX Example ------- char *q = (char *)malloc(20); free(q); File: libc.info, Node: freopen, Next: frexp, Prev: free, Up: Alphabetical List freopen ======= Syntax ------ #include <stdio.h> FILE *freopen(const char *filename, const char *mode, FILE *file); Description ----------- This function closes FILE if it was open, then opens a new file like `fopen(filename, mode)' but it reuses FILE. This is useful to, for example, associate `stdout' with a new file. Return Value ------------ The new file, or `NULL' on error. Portability ----------- ANSI, POSIX Example ------- freopen("/tmp/stdout.dat", "wb", stdout); File: libc.info, Node: frexp, Next: fscanf, Prev: freopen, Up: Alphabetical List frexp ===== Syntax ------ #include <math.h> double frexp(double x, int *pexp); Description ----------- This function separates the given value X into a mantissa m in the range `[0.5,1)' and an exponent e, such that m*2^e = X. It returns the value of the mantissa and stores the integer exponent in *PEXP. Return Value ------------ The mantissa. If the value of X is `NaN' or `Inf', the return value is `NaN', zero is stored in `*pexp', and `errno' is set to `EDOM'. If X is zero, *PEXP and the return value are also both zero. Portability ----------- ANSI, POSIX File: libc.info, Node: fscanf, Next: fseek, Prev: frexp, Up: Alphabetical List fscanf ====== Syntax ------ #include <stdio.h> int fscanf(FILE *file, const char *format, ...); Description ----------- This function scans formatted text from FILE and stores it in the variables pointed to by the arguments. *Note scanf::. Return Value ------------ The number of items successfully scanned. Portability ----------- ANSI, POSIX File: libc.info, Node: fseek, Next: fsetpos, Prev: fscanf, Up: Alphabetical List fseek ===== Syntax ------ #include <stdio.h> int fseek(FILE *file, long offset, int mode); Description ----------- This function moves the file pointer for FILE according to MODE: `SEEK_SET' The file pointer is moved to the offset specified. `SEEK_CUR' The file pointer is moved relative to its current position. `SEEK_END' The file pointer is moved to a position OFFSET bytes from the end of the file. The offset is usually nonpositive in this case. *Warning!* The ANSI standard only allows values of zero for OFFSET when MODE is not `SEEK_SET' and the file has been opened as a text file. Although this restriction is not enforced, beware that there is not a one-to-one correspondence between file characters and text characters under MS-DOS, so some `fseek' operations may not do exactly what you expect. Also, since `lseek' under DOS does not return an error indication when you try to move the file pointer before the beginning of the file, neither will `fseek'. Portable programs should call `ftell' after `fseek' to get the actual position of the file pointer. Note that DOS does not mind if you seek before the beginning of the file, like seeking from the end of the file by more than the file's size. Therefore, `lseek' will not return with an error in such cases either. Return Value ------------ Zero if successful, nonzero if not. Portability ----------- ANSI, POSIX Example ------- fseek(stdin, 12, SEEK_CUR); /* skip 12 bytes */ File: libc.info, Node: fsetpos, Next: __FSEXT_add_open_handler, Prev: fseek, Up: Alphabetical List fsetpos ======= Syntax ------ #include <stdio.h> int fsetpos(FILE *file, const fpos_t *offset); Description ----------- This function moves the file pointer for FILE to position OFFSET, as recorded by `fgetpos'. *Note fgetpos::. *Note fseek::. Return Value ------------ Zero if successful, nonzero if not. Portability ----------- ANSI, POSIX File: libc.info, Node: __FSEXT_add_open_handler, Next: __FSEXT_alloc_fd, Prev: fsetpos, Up: Alphabetical List __FSEXT_add_open_handler ======================== Syntax ------ #include <sys/fsext.h> int __FSEXT_add_open_handler(__FSEXT_Function *_function); Description ----------- This function is part of the *Note File System Extensions::. It is used to add a handler for functions that do not get passed descriptors, such as `_open' and `_creat'. Portability ----------- not ANSI, not POSIX Example ------- static int _my_handler(__FSEXT_Fnumber n, int *rv, va_list args) { . . . } int main() { __FSEXT_add_open_handler(_my_handler); } File: libc.info, Node: __FSEXT_alloc_fd, Next: __FSEXT_call_open_handlers, Prev: __FSEXT_add_open_handler, Up: Alphabetical List __FSEXT_alloc_fd ================ Syntax ------ #include <sys/fsext.h> int __FSEXT_alloc_fd(__FSEXT_Function *_function); Description ----------- This function is part of the *Note File System Extensions::. It is used by extensions that fully emulate the I/O functions, and thus don't have a corresponding DOS file handle. Upon the first call, this function opens DOS's `NUL' device, so as to allocate a handle that DOS won't then reuse. Upon subsequent calls, that handle is duplicated by calling the DOS `dup' function; this makes all of the handles use a single entry in the System File Table, and thus be independent of what the `FILES=' parameter of `CONFIG.SYS' says. `__FSEXT_alloc_fd' also assigns the handler function for the handle it returns. The module is responsible for calling `_close' on the descriptor after setting the handler function to zero in the extended close handler. Return Value ------------ If successful, a new file descriptor is returned. On error, a negative number is returned and ERRNO is set to indicate the error. Portability ----------- not ANSI, not POSIX Example ------- int socket() { int fd = __FSEXT_alloc_fd(socket_handler); init_socket(fd); return fd; } File: libc.info, Node: __FSEXT_call_open_handlers, Next: __FSEXT_get_data, Prev: __FSEXT_alloc_fd, Up: Alphabetical List __FSEXT_call_open_handlers ========================== Syntax ------ #include <sys/fsext.h> int __FSEXT_call_open_handlers(__FSEXT_Fnumber _function_number, int *rv, va_list _args); Description ----------- This function is part of the *Note File System Extensions::. It is used internally to libc.a to allow extensions to get an opportunity to override the `_open' and `_creat' functions. Portability ----------- not ANSI, not POSIX File: libc.info, Node: __FSEXT_get_data, Next: __FSEXT_get_function, Prev: __FSEXT_call_open_handlers, Up: Alphabetical List __FSEXT_get_data ================ Syntax ------ #include <sys/fsext.h> void *__FSEXT_get_data(int _fd); Description ----------- This function is part of the *Note File System Extensions::. It is used to retrieve a descriptor-specific pointer that was previously stored by `__FSEXT_set_data' (*note __FSEXT_set_data::.). The pointer is not otherwise used. *Note __FSEXT_set_data::, for an example of how this may be used. Return Value ------------ Returns the stored pointer, or NULL if there was an error (or no pointer had been stored). Portability ----------- not ANSI, not POSIX File: libc.info, Node: __FSEXT_get_function, Next: __FSEXT_set_data, Prev: __FSEXT_get_data, Up: Alphabetical List __FSEXT_get_function ==================== Syntax ------ #include <sys/fsext.h> __FSEXT_Function *__FSEXT_get_function(int _fd); This function is part of the *Note File System Extensions::. It is used internal to libc.a to redirect I/O requests to the appropriate extensions. Portability ----------- not ANSI, not POSIX Example ------- _read(int fd, void *buf, int len) { __FSEXT_Function *func = __FSEXT_get_function(fd); if (func) { int rv; if (func(__FSEXT_read, &rv, &fd)) return rv; } /* rest of read() */ } File: libc.info, Node: __FSEXT_set_data, Next: __FSEXT_set_function, Prev: __FSEXT_get_function, Up: Alphabetical List __FSEXT_set_data ================ Syntax ------ #include <sys/fsext.h> void * __FSEXT_set_data(int _fd, void *_data); Description ----------- This function is part of the *Note File System Extensions::. It is used to store a descriptor-specific pointer that can later be retrieved by `__FSEXT_get_data' (*note __FSEXT_get_data::.). The pointer is not otherwise used. This is useful when writing an extension that may be handling several open pseudo-files. `__FSEXT_set_data' can be used when creating or opening the file to store a pointer to data about the specific file. Later, when specific operation needs to be done (e.g. read, write, etc.) a pointer to pseudo-file associated with the file descriptor can be fetched with `__FSEXT_get_data'. Return Value ------------ Returns the pointer you passed it, or NULL if there was an error. Portability ----------- not ANSI, not POSIX Example ------- typedef struct { void* Ptr; off_t Current_Ofs; size_t Size; } _mem_file_t; int my_fsext(__FSEXT_Fnumber Op, int* RV, va_list Args) { const char* Path; void* Buffer; size_t Size; int fd; _mem_file_t* MPtr; switch (Op) { case __FSEXT_creat: /* Create a new memory file */ Path = va_list(Args, const char*); /* Check to see if we should create a new file */ if (strnicmp("/tmp/", Path, 5) != 0) return 0; /* Allocate some memory to keep info on our fake file */ MPtr = malloc(sizeof(_mem_file_t)); if (!MPtr) return 0; memset(MPtr, 0, sizeof(_mem_file_t)); /* Get a file descriptor we can use */ fd = __FSEXT_alloc_fd(my_fsext); if (fd < 0) { free(MPtr); return 0; } /* Now store our note about this file descriptor so we can lookup it up quickly later. */ __FSEXT_set_data(fd, MPtr); /* Return the file descriptor *RV = fd; return 1; case __FSEXT_read: /* Read from our memory file. */ fd = va_list(Args, int); Buffer = va_list(Args, void*); Size = va_list(Args, size_t); /* Look up the information about this file */ MPtr = __FSEXT_get_data(fd); if (!MPtr) { *RV = -1; return 1; } if (MPtr->Current_Ofs >= MPtr->Size) { *RV = 0; return 1; } if (Size > (MPtr->Size - MPtr->Current_Ofs)) Size = MPtr->Size - MPtr->Current_Ofs; memcpy(Buffer, (char*) MPtr->Ptr+MPtr->Current_Ofs, Size); MPtr->Current_Ofs += Size; *RV = Size; return 1; ... } } File: libc.info, Node: __FSEXT_set_function, Next: fstat, Prev: __FSEXT_set_data, Up: Alphabetical List __FSEXT_set_function ==================== Syntax ------ #include <sys/fsext.h> int __FSEXT_set_function(int _fd, __FSEXT_Function *_function); Description ----------- This function is part of the *Note File System Extensions::. It is used to set the handler function for those extensions that use DOS files for I/O. One situation where you might need this is when you must catch output to the terminal and play some tricks with it, like colorize it or redirect it to another device. Return Value ------------ Zero in case of success, non-zero in case of failure (like if _FD is negative). Portability ----------- not ANSI, not POSIX Example ------- #include <sys/fsext.h> #include <conio.h> /* A simple example of a write handler which converts DOS I/O to the screen into direct writes to video RAM. */ static int my_screen_write (__FSEXT_Fnumber func, int *retval, va_list rest_args) { char *buf, *mybuf; size_t buflen; int fd = va_arg (rest_args, int); if (func != __FSEXT_write || !isatty (fd)) return 0; /* and the usual DOS call will be issued */ buf = va_arg (rest_args, char *); buflen = va_arg (rest_args, size_t); mybuf = alloca (buflen + 1); memcpy (mybuf, buf, buflen); mybuf[buflen] = '\0'; cputs (mybuf); *retval = buflen; return 1; /* meaning that we handled the call */ } /* Install our handler. The `attribute constructor' causes this function to be called by the startup code. */ static void __attribute__((constructor)) install_screen_write_handler (void) { __FSEXT_set_function (fileno (stdout), my_screen_write); } File: libc.info, Node: fstat, Next: fsync, Prev: __FSEXT_set_function, Up: Alphabetical List fstat ===== Syntax ------ #include <sys/stat.h> int fstat(int file, struct stat *sbuf); Description ----------- This function obtains the status of the open file FILE and stores it in SBUF. *Note stat::, for the description of members of `struct stat'. Some members of `struct stat' are very expensive to compute. If your application is a heavy user of `fstat' and is too slow, you can disable computation of the members your application doesn't need, as described in *Note _djstat_flags::. Return Value ------------ Zero on success, nonzero on failure (and ERRNO set). Portability ----------- not ANSI, POSIX Example ------- struct stat s; fstat(fileno(stdin), &s); if (S_ISREG(s.st_mode)) puts("STDIN is a redirected disk file"); else if (S_ISCHR(s.st_mode)) puts("STDIN is a character device"); Bugs ---- If a file was open in write-only mode, its execute mode bits might be incorrectly reported as if the file were non-executable. This is because some executables are only recognized by reading their first two bytes, which cannot be done for files open in write-only mode. For `fstat' to return correct info, you should make sure that all the data written to the file has been delivered to the operating system, e.g. by calling both `fflush' and `fsync'. Otherwise, the buffering of the library I/O functions and the OS might cause stale info to be returned. Implementation Notes -------------------- Supplying a 100% Unix-compatible `fstat' function under DOS is an implementation nightmare. The following notes describe some of the obscure points specific to `fstat's behavior in DJGPP. 1. The `drive' for character devices (like `con', `/dev/null' and others is returned as -1. For drives networked by Novell Netware, it is returned as -2. 2. The starting cluster number of a file serves as its inode number. For files whose starting cluster number is inaccessible (empty files, files on networked drives, etc.) the `st_inode' field will be `invented' in a way which guarantees that no two different files will get the same inode number (thus it is unique). This invented inode will also be different from any real cluster number of any local file. However, only for local, non-empty files/directories the inode is guaranteed to be consistent between `stat' and `fstat' function calls. 3. The WRITE access mode bit is set only for the user (unless the file is read-only, hidden or system). EXECUTE bit is set for directories, files which can be executed from the DOS prompt (batch files, .com, .dll and .exe executables) or run by `go32-v2.exe'. For files which reside on networked drives under Novell Netware, this can sometimes fail, in which case only the read access bit is set. 4. The variable `_djstat_flags' (*note _djstat_flags::.) controls what hard-to-get fields of `struct stat' are needed by the application. File: libc.info, Node: fsync, Next: ftell, Prev: fstat, Up: Alphabetical List fsync ===== Syntax ------ #include <unistd.h> int fsync(int file); Description ----------- Forces all information about the file with the given descriptor to be synchronized with the disk image. Works by calling DOS function 0x68. *Warning*: External disk caches are not flushed by this function. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- fsync(fileno(stdout)); File: libc.info, Node: ftell, Next: ftime, Prev: fsync, Up: Alphabetical List ftell ===== Syntax ------ #include <stdio.h> long ftell(FILE *file); Description ----------- Returns the current file position for `file'. This is suitable for a future call to `fseek'. Return Value ------------ The file position, or -1 on error. Portability ----------- ANSI, POSIX Example ------- long p = ftell(stdout); File: libc.info, Node: ftime, Next: ftruncate, Prev: ftell, Up: Alphabetical List ftime ===== Syntax ------ #include <sys/timeb.h> int ftime(struct timeb *buf); Description ----------- This function stores the current time in the structure BUF. The format of `struct timeb' is: struct timeb { time_t time; /* seconds since 00:00:00 GMT 1/1/1970 */ unsigned short millitm; /* milliseconds */ short timezone; /* difference between GMT and local, minutes */ short dstflag; /* set if daylight savings time in affect */ }; Return Value ------------ Zero on success, nonzero on error. Portability ----------- not ANSI, not POSIX Example ------- struct timeb t; ftime(&t); File: libc.info, Node: ftruncate, Next: ftw, Prev: ftime, Up: Alphabetical List ftruncate ========= Syntax ------ #include <unistd.h> int ftruncate(int handle, off_t where); Description ----------- This function truncates the file open on HANDLE at byte position WHERE. The file pointer associated with HANDLE is not changed. Note that this function knows nothing about buffering by stdio functions like `fwrite' and `fprintf', so if HANDLE comes from a `FILE' object, you need to call `fflush' before calling this function. Return Value ------------ Zero for success, nonzero for failure. Portability ----------- not ANSI, not POSIX Example ------- int x = open("data", O_WRONLY); ftruncate(x, 1000); close(x); File: libc.info, Node: ftw, Next: _fwalk, Prev: ftruncate, Up: Alphabetical List ftw === Syntax ------ #include <ftw.h> int ftw(const char *dir, int (*func)(const char *path, struct stat *stbuf, int flag), int depth); Description ----------- This function recursively descends the directory hierarchy which starts with DIR. For each file in the hierarchy, `ftw' calls the user-defined function FUNC which is passed a pointer to a `NULL'-terminated character array in PATH holding the full pathname of the file, a pointer to a `stat' structure (*note stat::.) STBUF with a filesystem information about that file, and an integer FLAG. Possible values of FLAG are: `FTW_F' This is a regular file. `FTW_D' This is a directory. `FTW_VL' This is a volume label. `FTW_DNR' This is a directory which cannot be read with `readdir()'. (This will never happen in DJGPP.) `FTW_NS' This file exists, but `stat' fails for it. If FLAG is `FTW_DNR', the descendants of that directory won't be processed. If FLAG is `FTW_NS', then STBUF will be garbled. This function always visits a directory before any of its siblings. The argument DIR must be a directory, or `ftw' will fail and set ERRNO to `ENOTDIR'. The function FUNC is called with DIR as its argument before the recursive descent begins. The DEPTH argument has no meaning in the DJGPP implementation and is always ignored. The tree traversal continues until one of the following events: (1) The tree is exhausted (i.e., all descendants of DIR are processed). In this case, `ftw' returns 0, meaning a success. (2) An invocation of FUNC returns a non-zero value. In this case, `ftw' stops the tree traversal and returns whatever FUNC returned. (3) An error is detected within `ftw'. In that case, `ftw' returns -1 and sets ERRNO (*note errno::.) to a suitable value. Return Value ------------ Zero in case the entire tree was successfully traversed, -1 if `ftw' detected some error during its operation, or any other non-zero value which was returned by the user-defined function FUNC. Implementation Notes -------------------- This function uses `malloc' (*note malloc::.) for dynamic memory allocation during its operation. If FUNC disrupts the normal flow of code execution by e.g. calling `longjump' or if an interrupt handler which never returns is executed, this memory will remain permanently allocated. This function calls `opendir()' and `readdir()' functions to read the directory entries. Therefore, you can control what files will your FUNC get by setting the appropriate bits in the external variable __OPENDIR_FLAGS. *Note opendir::, for description of these bits. This function also calls `stat' for every directory entry it passes to FUNC. If your application only needs some part of the information returned in the `stat' structure, you can make your application significantly faster by setting bits in the external variable _DJSTAT_FLAGS (*note _djstat_flags::. for details). The most expensive `stat' features are `_STAT_EXEC_MAGIC' and `_STAT_DIRSIZE'. Portability ----------- not ANSI, not POSIX Example ------- #include <stdlib.h> int file_walker(const char *path, struct stat *sb, int flag) { char *base; printf("%s:\t%u\t", path, sb->st_size); if (S_ISLABEL(sb->st_mode)) printf("V"); if (S_ISDIR(sb->st_mode)) printf("D"); if (S_ISCHR(sb->st_mode)) printf("C"); if (sb->st_mode & S_IRUSR) printf("r"); if (sb->st_mode & S_IWUSR) printf("w"); if (sb->st_mode & S_IXUSR) printf("x"); if (flag == FTW_NS) printf(" !!no_stat!!"); printf("\n"); base = strrchr(path, '/'); if (base == 0) base = strrchr(path, '\\'); if (base == 0) base = strrchr(path, ':'); if (strcmp(base == 0 ? path : base + 1, "xxxxx") == 0) return 42; return 0; } int main(int argc, char *argv[]) { if (argc > 1) { char msg[80]; sprintf(msg, "file_tree_walk: %d", ftw(argv[1], file_walker, 0)); if (errno) perror(msg); else puts(msg); } else printf("Usage: %s dir\n", argv[0]); return 0; } File: libc.info, Node: _fwalk, Next: fwrite, Prev: ftw, Up: Alphabetical List _fwalk ====== Syntax ------ #include <libc/file.h> void _fwalk(void (*function)(FILE *file)); Description ----------- For each open file in the system, the given FUNCTION is called, passing the file pointer as its only argument. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- void pfile(FILE *x) { printf("FILE at %p\n", x); } _fwalk(pfile); File: libc.info, Node: fwrite, Next: gcvt, Prev: _fwalk, Up: Alphabetical List fwrite ====== Syntax ------ #include <stdio.h> size_t fwrite(void *buffer, size_t size, size_t number, FILE *file); Description ----------- This function writes SIZE*NUMBER characters from BUFFER to FILE. Return Value ------------ The number of items of size SIZE written, or less if there was an error. Portability ----------- ANSI, POSIX Example ------- int foo[10]; fwrite(foo, sizeof(int), 10, stdin); File: libc.info, Node: gcvt, Next: _get_dev_info, Prev: fwrite, Up: Alphabetical List gcvt ==== Syntax ------ #include <stdlib.h> char * gcvt (double value, int ndigits, char *buf) Description ----------- This function converts its argument VALUE into a null-terminated string of NDIGITS significant digits in BUF. BUF should have enough space to hold at least `NDIGITS + 7' characters. The result roughly corresponds to what is obtained by the following snippet: (void) sprintf(buf, "%.*g", ndigits, value); except that trailing zeros and trailing decimal point are suppressed. The least-significant digit in BUF is rounded. `ecvtbuf' produces the string "NaN" if VALUE is a NaN, and "Inf" if VALUE is an infinity. Return Value ------------ A pointer to BUF. Portability ----------- not ANSI, not POSIX Example ------- #include <stdlib.h> #include <stdio.h> #include <math.h> char vbuf[20]; /* This will print " 3.14159". */ printf ("%s", gcvt (M_PI, 5, buf)); File: libc.info, Node: _get_dev_info, Next: _get_dos_version, Prev: gcvt, Up: Alphabetical List _get_dev_info ============= Syntax ------ #include <io.h> short _get_dev_info(int handle); Description ----------- Given a file handle in HANDLE, this function returns the info word from DOS IOCTL function 0 (Int 21h/AX=4400h). HANDLE must refer to an open file or device, otherwise the call will fail (and set ERRNO to `EBADF'). In case of success, the returned value is the coded information from the system about the character device or the file which is referenced by the file handle HANDLE. The following table shows the meaning of the individual bits in the return value: For a character device: Bit(s) Description 14 Device can process IOCTL functions 02h and 03h 13 Device supports output-until-busy 11 Device supports OPEN/CLOSE calls 8 Unknown; set by MS-DOS 6.2x `KEYBXX.COM' 7 Always set for character devices 6 End of file on input 5 Device is in *raw* (binary) mode 4 Device uses Int 29h 3 Clock device 2 NUL device 1 Standard output device 0 Standard input device For a block device (a disk file): Bit(s) Description 15 Device is remote (networked drive) 14 Don't set file time stamp on close 11 If set, non-removable media 11 If clear, media is removable (e.g. floppy disk) 8 Generate Int 24h if full disk or read past EOF 7 Always clear for disk files 6 File has not been written to 5-0 Drive number (0 = A:) Note that the functionality indicated by bit 8 for the block devices is only supported by DOS version 4. "Cooked" mode means that on input `C-<C>', `C-<P>', `C-<S>' and `C-<Z>' are processed, on output `TAB's are expanded into spaces and `CR' character is added before each `LF', and input is terminated when the <RET> key is pressed. In contrast, in "raw" mode, all the special characters are passed verbatim, and the read operation waits until the specified number of characters has been read. Return Value ------------ The device information word described above. In case of error, -1 is returned and ERRNO is set to `EBADF'. Portability ----------- not ANSI, not POSIX Example ------- int fd = open ("CLOCK$", O_RDONLY | O_BINARY); int clock_info = _get_dev_info (fd); File: libc.info, Node: _get_dos_version, Next: _get_volume_info, Prev: _get_dev_info, Up: Alphabetical List _get_dos_version ================ Syntax ------ #include <dos.h> extern unsigned short _osmajor, _osminor; extern const char * _os_flavor; unsigned short _get_dos_version(int true_version); Description ----------- This function gets the host OS version and flavor. If the argument TRUE_VERSION is non-zero, it will return a `true' version number, which is unaffected by possible tinkering with SETVER TSR program. (This is only available in DOS 5.0 or later.) The external variables `_osmajor' and `_osminor' will always be set to the major and minor parts of the `advertised' version number, possibly changed by SETVER, even if TRUE_VERSION is non-zero. You typically need the true version when you need an intimate knowledge of the host OS internals, like when using undocumented features. Note that some DOS clones (notably, DR-DOS) do not support DOS function required to report the true DOS version; for these, the version reported might be affected by SETVER even if TRUE_VERSION is non-zero. The external variable `_os_flavor' will point to a string which describes the OEM name of the host OS variety. Return Value ------------ `_get_dos_version()' returns the version number (true version number, if TRUE_VERSION is non-zero) as a 16-bit number: the major part of the version in the upper 8 bits, the minor part in the lower 8 bits. For instance, DOS version 6.20 will be returned as 0x0614. Portability ----------- not ANSI, not POSIX Example ------- unsigned short true_dos_version = _get_dos_version(1); if (true_dos_version < 0x0614) /* require DOS 6.20 or later */ puts("This program needs DOS 6.20 or later to run"); else printf("You are running %s variety of DOS\n", _os_flavor); File: libc.info, Node: _get_volume_info, Next: getc, Prev: _get_dos_version, Up: Alphabetical List _get_volume_info ================ Syntax ------ #include <fcntl.h> unsigned _get_volume_info (const char *path, int *max_file_len, int *max_path_len, char *fsystype); Description ----------- This function returns filesystem information about the volume where PATH resides. Only the root directory name part is actually used; if PATH does not specify the drive explicitly, or is a `NULL' pointer, the current drive is used. Upon return, the variable pointed to by MAX_FILE_LEN contains the maximum length of a filename (including the terminating zero), the variable pointed to by MAX_PATH_LEN contains the maximum length of a pathname (including the terminating zero), and a string that identifies the filesystem type (e.g., "FAT", "NTFS" etc.) is placed into the buffer pointed to by FSYSTYPE, which should be long enough (32 bytes are usually enough). If any of these pointers is a `NULL' pointer, it will be ignored. The function returns various flags that describe features supported by the given filesystem as a bit-mapped number. The following bits are currently defined: `_FILESYS_CASE_SENSITIVE' Specifies that file searches are case-sensitive. `_FILESYS_CASE_PRESERVED' Filename letter-case is preserved in directory entries. `_FILESYS_UNICODE' Filesystem uses Unicode characters in file and directory names. `_FILESYS_LFN_SUPPORTED' Filesystem supports the "Long File Name" (LFN) API. `_FILESYS_VOL_COMPRESSED' This volume is compressed. `_FILESYS_UNKNOWN' The underlying system call failed. This usually means that the drive letter is invalid, like when a floppy drive is empty or a drive with that letter doesn't exist. Return value ------------ A combination of the above bits if the LFN API is supported, or 0 (and `errno' set to `ENOSYS') if the LFN API is not supported by the OS. If the drive letter is invalid, the function returns `_FILESYS_UNKNOWN' and sets `errno' to either `ENODEV' or `ENXIO'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: getc, Next: getcbrk, Prev: _get_volume_info, Up: Alphabetical List getc ==== Syntax ------ #include <stdio.h> int getc(FILE *file); Description ----------- Get one character from FILE. Return Value ------------ The character ([0..255]) or `EOF' if eof or error. Portability ----------- ANSI, POSIX Example ------- int c; while ((c=getc(stdin)) != EOF) putc(c, stdout); File: libc.info, Node: getcbrk, Next: getch, Prev: getc, Up: Alphabetical List getcbrk ======= Syntax ------ #include <dos.h> int getcbrk(void); Description ----------- Get the setting of the Ctrl-C checking flag in MS-DOS. *Note setcbrk::. Return Value ------------ 0 if not checking, 1 if checking. Portability ----------- not ANSI, not POSIX File: libc.info, Node: getch, Next: getchar, Prev: getcbrk, Up: Alphabetical List getch ===== Syntax ------ #include <conio.h> int getch(void); Description ----------- A single character from the predefined standard input handle is read and returned. The input is not buffered. If there is a character pending from `ungetch' (*note ungetch::.), it is returned instead. The character is not echoed to the screen. This function doesn't check for special characters like `Ctrl-<C>'. If the standard input handle is connected to the console, any pending output in the `stdout' and `stderr' streams is flushed before reading the input, if these streams are connected to the console. Return Value ------------ The character. Portability ----------- not ANSI, not POSIX File: libc.info, Node: getchar, Next: getche, Prev: getch, Up: Alphabetical List getchar ======= Syntax ------ #include <stdio.h> int getchar(void); Description ----------- The same as `fgetc(stdin)' (*note fgetc::.). Return Value ------------ The character, or `EOF'. Portability ----------- ANSI, POSIX File: libc.info, Node: getche, Next: getcwd, Prev: getchar, Up: Alphabetical List getche ====== Syntax ------ #include <conio.h> int getche(void); Description ----------- A single character from the predefined standard input handle is read and returned. The input is not buffered. If there is a character pending from `ungetch' (*note ungetch::.), it is returned instead. The character is echoed to the screen. This function doesn't check for special characters like `Ctrl-<C>'. If the standard input handle is connected to the console, any pending output in the `stdout' and `stderr' streams is flushed before reading the input, if these streams are connected to the console. Return Value ------------ The character. Portability ----------- not ANSI, not POSIX File: libc.info, Node: getcwd, Next: getdate, Prev: getche, Up: Alphabetical List getcwd ====== Syntax ------ #include <unistd.h> char *getcwd(char *buffer, int max); Description ----------- Get the current directory. The return value includes the drive specifier. If BUFFER is `NULL', `getcwd' allocates memory with `malloc'. This call fails if more than MAX characters are required to specify the current directory. Return Value ------------ The buffer, either BUFFER or a newly-allocated buffer, or `NULL' on error. Portability ----------- not ANSI, POSIX Example ------- char *buf = (char *)malloc(PATH_MAX); if (buf && getcwd(buf, PATH_MAX)) { printf("cwd is %s\n", buf); free(buf); } File: libc.info, Node: getdate, Next: getdfree, Prev: getcwd, Up: Alphabetical List getdate ======= Syntax ------ #include <dos.h> void getdate(struct date *); Description ----------- This function gets the current date. The return structure is as follows: struct date { short da_year; char da_day; char da_mon; }; *Note setdate::. *Note gettime::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- struct date d; getdate(&d); File: libc.info, Node: getdfree, Next: getdisk, Prev: getdate, Up: Alphabetical List getdfree ======== Syntax ------ #include <dos.h> void getdfree(unsigned char drive, struct dfree *ptr); Description ----------- This function gets information about the size and fullness of the given drive (0=default, 1=A:, etc). The return structure is as follows: struct dfree { unsigned df_avail; /* number of available clusters */ unsigned df_total; /* total number of clusters */ unsigned df_bsec; /* bytes per sector */ unsigned df_sclus; /* sectors per cluster */ }; Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- struct dfree d; getdfree(3, &d); /* drive C: */ File: libc.info, Node: getdisk, Next: getdtablesize, Prev: getdfree, Up: Alphabetical List getdisk ======= Syntax ------ #include <dir.h> int getdisk(void); Description ----------- Gets the current disk (0=A). *Note setdisk::. Return Value ------------ The current disk number. Portability ----------- not ANSI, not POSIX Example ------- printf("This drive is %c:\n", getdisk() + 'A'); File: libc.info, Node: getdtablesize, Next: getegid, Prev: getdisk, Up: Alphabetical List getdtablesize ============= Syntax ------ #include <unistd.h> int getdtablesize(void); Description ----------- Get the maximum number of open file descriptors the system supports. Return Value ------------ 255 Portability ----------- not ANSI, not POSIX File: libc.info, Node: getegid, Next: getenv, Prev: getdtablesize, Up: Alphabetical List getegid ======= Syntax ------ #include <unistd.h> int getegid(void); Description ----------- Get the effective group id. Return Value ------------ 42 Portability ----------- not ANSI, POSIX File: libc.info, Node: getenv, Next: geteuid, Prev: getegid, Up: Alphabetical List getenv ====== Syntax ------ #include <stdlib.h> char *getenv(const char *name); Description ----------- Get the setting of the environment variable NAME. Do not alter or free the returned value. Return Value ------------ The value, or `NULL' if that variable does not exist. Portability ----------- ANSI, POSIX Example ------- char *term = getenv("TERM"); File: libc.info, Node: geteuid, Next: getftime, Prev: getenv, Up: Alphabetical List geteuid ======= Syntax ------ #include <unistd.h> int geteuid(void); Description ----------- Gets the effective UID. Return Value ------------ 42 Portability ----------- not ANSI, POSIX File: libc.info, Node: getftime, Next: getgid, Prev: geteuid, Up: Alphabetical List getftime ======== Syntax ------ #include <dos.h> int getftime(int handle, struct ftime *ptr); Description ----------- Get the timestamp for the given file handle. The return structure is as follows: struct ftime { unsigned ft_tsec:5; /* 0-29, double to get real seconds */ unsigned ft_min:6; /* 0-59 */ unsigned ft_hour:5; /* 0-23 */ unsigned ft_day:5; /* 1-31 */ unsigned ft_month:4; /* 1-12 */ unsigned ft_year:7; /* since 1980 */ } Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- struct ftime t; getftime(fd, &t); File: libc.info, Node: getgid, Next: getgrent, Prev: getftime, Up: Alphabetical List getgid ====== Syntax ------ #include <unistd.h> int getgid(void); Description ----------- Get the current group id. Return Value ------------ 42 Portability ----------- not ANSI, POSIX File: libc.info, Node: getgrent, Next: getgrgid, Prev: getgid, Up: Alphabetical List getgrent ======== Syntax ------ #include <grp.h> struct group *getgrent(void); Description ----------- This function returns the next available group entry. Note that for MS-DOS, this is simulated. If the environment variable GROUP is set, that is the name of the only group returned, else the only group is "dos". Thus, under DOS, `getgrent' will always fail on the second and subsequent calls. The return type of this and related function is as follows: struct group { gid_t gr_gid; /* result of getgid() */ char ** gr_mem; /* gr_mem[0] points to getenv("USER"/"LOGNAME") or "user" */ char * gr_name; /* getenv("GROUP") or "dos" */ }; Return Value ------------ The next structure, or `NULL' at the end of the list. Portability ----------- not ANSI, not POSIX Example ------- struct group *g; setgrent(); while ((g = getgrent()) != NULL) { printf("group %s gid %d\n", g->gr_name, g->gr_gid); } endgrent(); File: libc.info, Node: getgrgid, Next: getgrnam, Prev: getgrent, Up: Alphabetical List getgrgid ======== Syntax ------ #include <grp.h> extern struct group *getgrgid(int gid); Description ----------- This function returns the group entry that matches GID. *Note getgrent::, for the description of `struct group'. Return Value ------------ The matching group, or `NULL' if none match. Portability ----------- not ANSI, POSIX File: libc.info, Node: getgrnam, Next: getgroups, Prev: getgrgid, Up: Alphabetical List getgrnam ======== Syntax ------ #include <grp.h> struct group *getgrnam(char *name); Description ----------- This function returns the group entry for the group named NAME. *Note getgrent::, for the description of `struct group'. Return Value ------------ The matching group, or `NULL' if none match. Portability ----------- not ANSI, POSIX File: libc.info, Node: getgroups, Next: gethostname, Prev: getgrnam, Up: Alphabetical List getgroups ========= Syntax ------ #include <unistd.h> int getgroups(int size, gid_t *grouplist); Description ----------- This function always returns zero. It exists to assist porting from Unix. Return Value ------------ Zero. Portability ----------- not ANSI, POSIX File: libc.info, Node: gethostname, Next: getitimer, Prev: getgroups, Up: Alphabetical List gethostname =========== Syntax ------ #include <unistd.h> #include <sys/param.h> int gethostname (char *buf, int size); Description ----------- Get the name of the host the program is executing on. This name is obtained from the network software, if present, otherwise from the `"HOSTNAME"' environment variable, if present, finally defaulting to `"pc"'. The call fails if more than SIZE characters are required to specify the host name. A buffer size of `MAXGETHOSTNAME' is guaranteed to be enough. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- char *buf = (char *) malloc (MAXGETHOSTNAME); if (buf && 0 == gethostname (buf, MAXGETHOSTNAME)) printf ("We're on %s\n", buf); if (buf) free(buf); File: libc.info, Node: getitimer, Next: getkey, Prev: gethostname, Up: Alphabetical List getitimer ========= Syntax ------ #include <sys/time.h> int getitimer(int which, struct itimerval *value); Description ----------- This function gets the current value of the interval timer specified by WHICH into structure VALUE. Variable WHICH can have the value of `ITIMER_REAL' or `ITIMER_PROF'. *Note setitimer::, for more details about timers. Upon return, the `it_value' member of VALUE will hold the amount of time left until timer expiration, or zero if the timer has expired or was stopped by a previous call to `setitimer'. The `it_interval' member will hold the interval between two successive alarms as set by the last call to `setitimer' (but note that interval values less than the system clock granularity are rounded up to that granularity). The value returned in `it_interval' member is *not* set to zero when the timer is stopped, it always retains the interval that was last in use. Return Value ------------ Returns 0 on success, -1 on failure (and sets `errno'). Portability ----------- not ANSI, not POSIX File: libc.info, Node: getkey, Next: getlogin, Prev: getitimer, Up: Alphabetical List getkey ====== Syntax ------ #include <pc.h> #include <keys.h> int getkey(void); Description ----------- Waits for the user to press one key, then returns that key. Alt-key combinations have 0x100 added to them. Extended keys return their non-extended codes. The file `keys.h' has symbolic names for many of the keys. *Note getxkey::. Return Value ------------ The key pressed. Portability ----------- not ANSI, not POSIX Example ------- while (getkey() != K_Alt_3) do_something(); File: libc.info, Node: getlogin, Next: getlongpass, Prev: getkey, Up: Alphabetical List getlogin ======== Syntax ------ #include <unistd.h> char *getlogin(void); Description ----------- Get the login ID of the user. Return Value ------------ Returns the value of the `USER' environment variable, else the `LOGNAME' environment variable, else `"dosuser"'. Portability ----------- not ANSI, POSIX Example ------- printf("I am %s\n", getlogin()); File: libc.info, Node: getlongpass, Next: getmntent, Prev: getlogin, Up: Alphabetical List getlongpass =========== Syntax ------ #include <stdlib.h> int getlongpass(const char *prompt, char *password, int max_length) Description ----------- This function reads up to a Newline (CR or LF) or EOF (Ctrl-D or Ctrl-Z) from the standard input, without an echo, after prompting with a null-terminated string PROMPT. It puts a null-terminated string of at most MAX_LENGTH - 1 first characters typed by the user into a buffer pointed to by PASSWORD. Pressing Ctrl-C or Ctrl-Break will cause the calling program to `exit(1)'. Return Value ------------ Zero if successful, -1 on error (and ERRNO is set to an appropriate value). Portability ----------- not ANSI, not POSIX Example ------- char password[MAX_PASS]; (void)getlongpass("Password: ", password, MAX_PASS); File: libc.info, Node: getmntent, Next: getopt, Prev: getlongpass, Up: Alphabetical List getmntent ========= Syntax ------ #include <mntent.h> struct mntent *getmntent(FILE *filep); Description ----------- This function returns information about the various drives that are available to your program. Beginning with drive `A:', information is retrieved for successive drives with successive calls to `getmntent'. Note that drives `A:' and `B:' will only be returned if there is an MS-DOS formatted disk in the drive; empty drives are skipped. For systems with a single floppy drive, it is returned as if it were mounted on `A:/' or `B:/', depending on how it was last referenced (and if there is a disk in the drive). For each drive scanned, a pointer to a static structure of the following type is returned: struct mntent { char * mnt_fsname; /* The name of this file system */ char * mnt_dir; /* The root directory of this file system */ char * mnt_type; /* Filesystem type */ char * mnt_opts; /* Options, see below */ int mnt_freq; /* -1 */ int mnt_passno; /* -1 */ long mnt_time; /* -1 */ }; DJGPP implementation returns the following in the first 4 fields of `struct mntent': `mnt_fsname' For networked and CD-ROM drives, this is the name of root directory in the form `\\HOST\PATH' (this is called a "UNC name"). For drives compressed with DoubleSpace, `mnt_fsname' is the string `X:\DBLSPACE.NNN', where X is the drive letter of the host drive and NNN is the sequence number of the Compressed Volume File. For drives compressed with Stacker, `mnt_fsname' is the string `X:\STACVOL.NNN', where X and NNN are as for DoubleSpace drives. For drives compressed with Jam (a shareware disk compression software), `mnt_fsname' is the full name of the Jam archive file. For SUBSTed drives, `mnt_fsname' is the actual directory name that that was SUBSTed to emulate a drive. JOINed drives get their `mnt_fsname' as if they were NOT JOINed (i.e., either the label name or the default `Drive X:'). For drives with a volume label, `mnt_fsname' is the name of the label; otherwise the string `Drive X:', where X is the drive letter. `mnt_dir' For most drives, this is the name of its root directory `X:/' (where X is the drive letter), except that JOINed drives get `mnt_dir' as the name of the directory to which they were JOINed. For systems with a single floppy drive (which can be referenced as either `a:/' or `b:/'), the mount directory will be returned as one of these, depending on which drive letter was last used to reference that drive. `mnt_type' "fd" for floppy disks "hd" for hard disks "dblsp" for disks compressed with DoubleSpace "stac" for disks compressed with Stacker "jam" for disks compressed with Jam "cdrom" for CD-ROM drives "ram" for RAM disks "subst" for SUBSTed directories "join" for JOINed disks "net" for networked drives `mnt_opts' The string `ro,dev=XX' for CD-ROM drives, `rw,dev=XX' for all the others, where XX is the hexadecimal drive number of the REAL drive on which this filesystem resides. That is, if you call `stat' on MNT_FSNAME, you will get the numeric equivalent of XX in `st_dev' member of `struct stat'. E.g., for drive `C:' you will get `rw,dev=02'. Note that SUBSTed and JOINed drives get the drive numbers as if SUBST and JOIN were *not* in effect. Return Value ------------ This function returns a pointer to a `struct mntent', or `NULL' if there are no more drives to report on. Portability ----------- not ANSI, not POSIX Example ------- struct mntent *m; FILE *f; f = setmntent("/etc/mnttab", "r"); while ((m = getmntent(f))) printf("Drive %s, name %s\n", m->mnt_dir, m->mnt_fsname); endmntent(f); File: libc.info, Node: getopt, Next: getpagesize, Prev: getmntent, Up: Alphabetical List getopt ====== Syntax ------ #include <unistd.h> int getopt(int argc, char * const *argv, const char *options); extern char *optarg; extern int optind, opterr, optopt; Description ----------- Parse options from the command line. The OPTIONS are a string of valid option characters. If a given option takes a parameter, that character should be followed by a colon. For each valid switch, this function sets `optarg' to the argument (if the switch takes one), sets `optind' to the index in ARGV that it is using, sets `optopt' to the option letter found, and returns the option letter found. If an unexpected option is found, `getopt' will return `?', and if `opterr' is nonzero, will print an error message to stderr. The special option `--' indicates that no more options follow on the command line, and cause `getopt' to stop looking. Return Value ------------ The option found, or -1 if no more options. Portability ----------- not ANSI, POSIX Example ------- int c; opterr = 0; while ((c=getopt(argc, argv, "vbf:")) != -1) { switch (c) { case 'v': verbose_flag ++; break; case 'b': binary_flag ++; break; case 'f': output_filename = optarg; break; case '?': printf("Unknown option %c\n", optopt); usage(); exit(1); } } File: libc.info, Node: getpagesize, Next: getpass, Prev: getopt, Up: Alphabetical List getpagesize =========== Syntax ------ #include <unistd.h> int getpagesize(void); Description ----------- Return the size of the native virtual memory page size. Return Value ------------ 4096 for the i386 and higher processors. Portability ----------- not ANSI, not POSIX File: libc.info, Node: getpass, Next: getpgrp, Prev: getpagesize, Up: Alphabetical List getpass ======= Syntax ------ #include <stdlib.h> char * getpass(const char *prompt) Description ----------- This function reads up to a Newline (CR or LF) or EOF (Ctrl-D or Ctrl-Z) from the standard input, without an echo, after prompting with a null-terminated string PROMPT. It returns the string of at most 8 characters typed by the user. Pressing Ctrl-C or Ctrl-Break will cause the calling program to `exit(1)'. Return Value ------------ A pointer to a static buffer which holds the user's response. The buffer will be overwritten by each new call. In case of any error in the lower I/O routines, a NULL pointer will be returned. Portability ----------- not ANSI, not POSIX Example ------- char *password = getpass("Password: "); File: libc.info, Node: getpgrp, Next: getpid, Prev: getpass, Up: Alphabetical List getpgrp ======= Syntax ------ #include <unistd.h> int getpgrp(void); Description ----------- Gets the process group, which is currently the same as the pid. Return Value ------------ The process group. Portability ----------- not ANSI, POSIX File: libc.info, Node: getpid, Next: getpwent, Prev: getpgrp, Up: Alphabetical List getpid ====== Syntax ------ #include <unistd.h> int getpid(void); Description ----------- Get the process ID, which uniquely identifies each program running on the system. Return Value ------------ The process ID. Portability ----------- not ANSI, POSIX File: libc.info, Node: getpwent, Next: getpwnam, Prev: getpid, Up: Alphabetical List getpwent ======== Syntax ------ #include <pwd.h> struct passwd *getpwent(void); Description ----------- This function retrieves the next available password file entry. For MS-DOS, this is simulated by providing exactly one entry: struct passwd { char * pw_name; /* getlogin() */ int pw_uid; /* getuid() */ int pw_gid; /* getgid() */ char * pw_dir; /* "/" or getenv("HOME") */ char * pw_shell; /* "/bin/sh" or getenv("SHELL") */ }; The `pw_name' member is returned as described under `getlogin' (*note getlogin::.). The `pw_uid' member is returned as described under `getuid' (*note getuid::.). `pw_gid' is returned as described under `getgid' (*note getgid::.). The `pw_dir' member is set to the value of the environment variable `HOME' if it is defined, or to `/' otherwise. `pw_shell' is set as follows: * If the environment variable `SHELL' is set, the value of `SHELL'. * If `SHELL' is not set, but `COMSPEC' is, the value of `COMSPEC'. * If neither of the above variables is defined, `pw_shell' is set to `"sh"'. Return Value ------------ The next passwd entry, or `NULL' if there are no more. Portability ----------- not ANSI, not POSIX Example ------- struct passwd *p; setpwent(); while ((p = getpwent()) != NULL) { printf("user %s name %s\n", p->pw_name, p->pw_gecos); } endpwent(); File: libc.info, Node: getpwnam, Next: getpwuid, Prev: getpwent, Up: Alphabetical List getpwnam ======== Syntax ------ #include <pwd.h> struct passwd *getpwnam(const char *name); Description ----------- This function gets the password file entry matching NAME. See *Note getpwent::, for the description of `struct passwd'. Return Value ------------ The matching record, or `NULL' if none match. Portability ----------- not ANSI, POSIX File: libc.info, Node: getpwuid, Next: getrlimit, Prev: getpwnam, Up: Alphabetical List getpwuid ======== Syntax ------ #include <pwd.h> struct passwd *getpwuid(uid_t uid); Description ----------- This function gets the password file entry matching UID. See *Note getpwent::, for the description of `struct passwd'. Return Value ------------ The matching record, or `NULL' if none match. Portability ----------- not ANSI, POSIX File: libc.info, Node: getrlimit, Next: getrusage, Prev: getpwuid, Up: Alphabetical List getrlimit ========= Syntax ------ #include <sys/resource.h> int getrlimit (int rltype, struct rlimit *rlimitp); Description ----------- This function gets the resource limit specified by RLTYPE and stores it in the buffer pointed to by RLIMITP. The `rlimit' structure is defined on `sys/resource.h' as follows: struct rlimit { long rlim_cur; /* current (soft) limit */ long rlim_max; /* maximum value for rlim_cur */ }; The following resource types can be passed in RLTYPE: `RLIMIT_CPU' CPU time in milliseconds. `RLIMIT_FSIZE' Maximum file size. `RLIMIT_DATA' Data size. `RLIMIT_STACK' Stack size. `RLIMIT_CORE' Core file size. `RLIMIT_RSS' Resident set size. `RLIMIT_MEMLOCK' Locked-in-memory address space. `RLIMIT_NPROC' Number of processes. `RLIMIT_NOFILE' Number of open files. Currently, only the `RLIMIT_STACK' and `RLIMIT_NOFILE' are meaningful: the first returns the value of `_stklen' (*note _stklen::.), the second the value returned by `sysconf(_SC_OPEN_MAX)' (*note sysconf::.). All other members of the `rlimit' structure are set to `RLIM_INFINITY', defined in `sys/resource.h' as `2^31 - 1'. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- struct rlimit rlimitbuf; int rc = getrlimit (RLIMIT_STACK, &rlimitbuf); File: libc.info, Node: getrusage, Next: gets, Prev: getrlimit, Up: Alphabetical List getrusage ========= Syntax ------ #include <sys/time.h> #include <sys/resource.h> int getrusage(int who, struct rusage *rusage); Description ----------- This function returns information about the running process. The structure `struct rusage' is defined on `<sys/resource.h>' as follows: struct rusage { struct timeval ru_utime; /* user time used */ struct timeval ru_stime; /* system time used */ long ru_maxrss; /* integral max resident set size */ long ru_ixrss; /* integral shared text memory size */ long ru_idrss; /* integral unshared data size */ long ru_isrss; /* integral unshared stack size */ long ru_minflt; /* page reclaims */ long ru_majflt; /* page faults */ long ru_nswap; /* swaps */ long ru_inblock; /* block input operations */ long ru_oublock; /* block output operations */ long ru_msgsnd; /* messages sent */ long ru_msgrcv; /* messages received */ long ru_nsignals; /* signals received */ long ru_nvcsw; /* voluntary context switches */ long ru_nivcsw; /* involuntary context switches */ }; Currently, the only field that is computed is `ru_utime'. It is computed as the total elapsed time used by the calling program. The remainder of the fields are set to zero. The WHO parameter must be `RUSAGE_SELF' or `RUSAGE_CHILDREN'. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- struct rusage r; getrusage(RUSAGE_SELF, &r); File: libc.info, Node: gets, Next: gettext, Prev: getrusage, Up: Alphabetical List gets ==== Syntax ------ #include <stdio.h> char *gets(char *buffer); Description ----------- Reads characters from `stdin', storing them in BUFFER, until either end of file or a newline is encountered. If any characters were stored, the BUFFER is then `NULL' terminated and its address is returned, else `NULL' is returned. Return Value ------------ The address of the buffer, or `NULL'. Portability ----------- ANSI, POSIX Example ------- char buf[1000]; while (gets(buf)) puts(buf); File: libc.info, Node: gettext, Next: gettextinfo, Prev: gets, Up: Alphabetical List gettext ======= Syntax ------ #include <conio.h> int gettext(int _left, int _top, int _right, int _bottom, void *_destin); Description ----------- Retrieve a block of screen characters into a buffer. Return Value ------------ 1 Portability ----------- not ANSI, not POSIX File: libc.info, Node: gettextinfo, Next: gettime, Prev: gettext, Up: Alphabetical List gettextinfo =========== Syntax ------ #include <conio.h> void gettextinfo(struct text_info *_r); Description ----------- This function returns the parameters of the current window on the screen. The return structure is this: struct text_info { unsigned char winleft; unsigned char wintop; unsigned char winright; unsigned char winbottom; unsigned char attribute; unsigned char normattr; unsigned char currmode; unsigned char screenheight; unsigned char screenwidth; unsigned char curx; unsigned char cury; }; The `normattr' field is the text attribute which was in effect before the program started. Portability ----------- not ANSI, not POSIX File: libc.info, Node: gettime, Next: gettimeofday, Prev: gettextinfo, Up: Alphabetical List gettime ======= Syntax ------ #include <dos.h> void gettime(struct time *); Description ----------- This function gets the current time. The return structure is as follows: struct time { unsigned char ti_min; unsigned char ti_hour; unsigned char ti_hund; unsigned char ti_sec; }; *Note settime::. *Note getdate::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- struct time t; gettime(&t); File: libc.info, Node: gettimeofday, Next: getuid, Prev: gettime, Up: Alphabetical List gettimeofday ============ Syntax ------ #include <time.h> int gettimeofday(struct timeval *tp, struct timezone *tzp); Description ----------- Gets the current GMT time and the local timezone information. The return structures are as follows: struct timeval { long tv_sec; /* seconds since 00:00:00 GMT 1/1/1970 */ long tv_usec; /* microseconds */ }; struct timezone { int tz_minuteswest; /* west of GMT */ int tz_dsttime; /* set if daylight saving time in affect */ }; If either TP or TZP are `NULL', that information is not provided. Note that although this function returns microseconds for compatibility reasons, the values are precise to less than 1/20 of a second only. The underlying DOS function has 1/20 second granularity, as it is calculated from the 55 ms timer tick count, so you won't get better than that with gettimeofday(). *Note settimeofday::. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: getuid, Next: getw, Prev: gettimeofday, Up: Alphabetical List getuid ====== Syntax ------ #include <unistd.h> int getuid(void); Description ----------- Returns the user ID. Return Value ------------ 42 Portability ----------- not ANSI, POSIX File: libc.info, Node: getw, Next: getwd, Prev: getuid, Up: Alphabetical List getw ==== Syntax ------ #include <stdio.h> int getw(FILE *file); Description ----------- Reads a single binary word in native format from FILE. *Note putw::. Return Value ------------ The value read, or `EOF' for end-of-file or error. Since `EOF' is a valid integer, you should use `feof' or `ferror' to detect this situation. Portability ----------- not ANSI, not POSIX Example ------- int i = getw(stdin); File: libc.info, Node: getwd, Next: getxkey, Prev: getw, Up: Alphabetical List getwd ===== Syntax ------ #include <unistd.h> char *getwd(char *buffer); Description ----------- Get the current directory and put it in BUFFER. The return value includes the drive specifier. Return Value ------------ BUFFER is returned. Portability ----------- not ANSI, not POSIX Example ------- char buf[PATH_MAX]; getwd(buf); File: libc.info, Node: getxkey, Next: glob, Prev: getwd, Up: Alphabetical List getxkey ======= Syntax ------ #include <pc.h> #include <keys.h> int getxkey(void); Description ----------- Waits for the user to press one key, then returns that key. Alt-key combinations have 0x100 added to them, and extended keys have 0x200 added to them. The file `keys.h' has symbolic names for many of the keys. *Note getkey::. Return Value ------------ The key pressed. Portability ----------- not ANSI, not POSIX Example ------- while (getxkey() != K_EEnd) do_something(); File: libc.info, Node: glob, Next: globfree, Prev: getxkey, Up: Alphabetical List glob ==== Syntax ------ #include <glob.h> int glob(const char *pattern, int flags, int (*errfunc)(const char *epath, int eerrno), glob_t *pglob); Description ----------- This function expands a filename wildcard which is passed as PATTERN. The pattern may include these special characters: `*' Matches zero of more characters. `?' Matches exactly one character (any character). `[...]' Matches one character from a group of characters. If the first character is `!', matches any character *not* in the group. A group is defined as a list of characters between the brackets, e.g. `[dkl_]', or by two characters separated by `-' to indicate all characters between and including these two. For example, `[a-d]' matches `a', `b', `c', or `d', and `[!a-zA-Z0-9]' matches any character that is not alphanumeric. `...' Matches all the subdirectories, recursively (VMS aficionados, rejoice!). `\' Causes the next character to not be treated as special. For example, `\[' matches a literal `['. If FLAGS includes `GLOB_NOESCAPE', this quoting is disabled and `\' is handled as a simple character. The variable FLAGS controls certain options of the expansion process. Possible values for _FLAGS are as follows: `GLOB_APPEND' Append the matches to those already present in the array `pglob->gl_pathv'. By default, `glob' discards all previous contents of `pglob->gl_pathv' and allocates a new memory block for it. If you use `GLOB_APPEND', `pglob' should point to a structure returned by a previous call to `glob'. `GLOB_DOOFFS' Skip `pglob->gl_offs' entries in `gl_pathv' and put new matches after that point. By default, `glob' puts the new matches beginning at `pglob->gl_pathv[0]'. You can use this flag both with `GLOB_APPEND' (in which case the new matches will be put after the first `pglob->gl_offs' matches from previous call to `glob'), or without it (in which case the first `pglob->gl_offs' entries in `pglob->gl_pathv' will be filled by `NULL' pointers). `GLOB_ERR' Stop when an unreadable directory is encountered and call user-defined function ERRFUNC. This cannot happen under DOS (and thus ERRFUNC is never used). `GLOB_MARK' Append a slash to each pathname that is a directory. `GLOB_NOCHECK' If no matches are found, return the pattern itself as the only match. By default, `glob' doesn't change `pglob' if no matches are found. `GLOB_NOESCAPE' Disable blackslash as an escape character. By default, backslash quotes special meta-characters in wildcards described above. `GLOB_NOSORT' Do not sort the returned list. By default, the list is sorted alphabetically. This flag causes the files to be returned in the order they were found in the directory. Given the pattern and the flags, `glob' expands the pattern and returns a list of files that match the pattern in a structure a pointer to which is passed via PGLOB. This structure is like this: typedef struct { size_t gl_pathc; char **gl_pathv; size_t gl_offs; } glob_t; In the structure, the `gl_pathc' field holds the number of filenames in `gl_pathv' list; this includes the filenames produced by this call, plus any previous filenames if `GLOB_APPEND' or `GLOB_DOOFFS' were set in FLAGS. The list of matches is returned as an array of pointers to the filenames; `gl_pathv' holds the address of the array. Thus, the filenames which match the pattern can be accessed as `gl_pathv[0]', `gl_pathv[1]', etc. If `GLOB_DOOFFS' was set in FLAGS, the new matches begin at offset given by `gl_offs'. Return Value ------------ Zero on success, or one of these codes: `GLOB_ABORTED' Not used in DJGPP implementation. `GLOB_NOMATCH' No files matched the given pattern. `GLOB_NOSPACE' Not enough memory to accomodate expanded filenames. `GLOB_ERR' Never happens on MSDOS, see above. Notes ----- `glob' will not match names of volume labels. On MSDOS, filenames are always matched case-insensitively. On filesystems that preserve letter-case in filenames (such as Windows 9x), matches are case-insensitive unless the pattern includes uppercase characters. On MSDOS, the list of expanded filenames will be returned in lower case, if all the characters of the pattern (except those between brackets [...]) are lower-case; if some of them are upper-case, the expanded filenames will be also in upper case. On filesystems that preserve letter-case in filenames, long filenames are returned as they are found in the directory entry; DOS-style 8+3 filenames are returned as on MSDOS (in lower case if the pattern doesn't include any upper-case letters, in upper case otherwise). When the environment variable `LFN' is set to `n', `glob' behaves on Windows 9x exactly as it does on MSDOS. Setting the environment variable `FNCASE' to `y', or setting the `_CRT0_FLAG_PRESERVE_FILENAME_CASE' bit in the `_crt0_startup_flags' variable (*note _crt0_startup_flags::.) suppresses any letter-case conversions in filenames and forces case-sensitive filename matching. *Note _preserve_fncase::. Portability ----------- not ANSI, POSIX Example ------- #include <stdlib.h> #include <string.h> #include <glob.h> /* Convert a wildcard pattern into a list of blank-separated filenames which match the wildcard. */ char * glob_pattern(char *wildcard) { char *gfilename; size_t cnt, length; glob_t glob_results; char **p; glob(wildcard, GLOB_NOCHECK, 0, &glob_results); /* How much space do we need? */ for (p = glob_results.gl_pathv, cnt = glob_results.gl_pathc; cnt; p++, cnt--) length += strlen(*p) + 1; /* Allocate the space and generate the list. */ gfilename = (char *) calloc(length, sizeof(char)); for (p = glob_results.gl_pathv, cnt = glob_results.gl_pathc; cnt; p++, cnt--) { strcat(gfilename, *p); if (cnt > 1) strcat(gfilename, " "); } globfree(&glob_results); return gfilename; } File: libc.info, Node: globfree, Next: gmtime, Prev: glob, Up: Alphabetical List globfree ======== Syntax ------ #include <glob.h> void globfree(glob_t *_pglob); Description ----------- Frees the memory associated with `_pglob'. Portability ----------- not ANSI, POSIX File: libc.info, Node: gmtime, Next: _go32_conventional_mem_selector, Prev: globfree, Up: Alphabetical List gmtime ====== Syntax ------ #include <time.h> struct tm *gmtime(const time_t *tod); Description ----------- Converts the time represented by TOD into a structure. The return structure has this format: struct tm { int tm_sec; /* seconds after the minute [0-60] */ int tm_min; /* minutes after the hour [0-59] */ int tm_hour; /* hours since midnight [0-23] */ int tm_mday; /* day of the month [1-31] */ int tm_mon; /* months since January [0-11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday [0-6] */ int tm_yday; /* days since January 1 [0-365] */ int tm_isdst; /* Daylight Savings Time flag */ long tm_gmtoff; /* offset from GMT in seconds */ char * tm_zone; /* timezone abbreviation */ }; Return Value ------------ A pointer to a static structure which is overwritten with each call. Portability ----------- ANSI, POSIX Example ------- time_t x; struct tm *t; time(&x); t = gmtime(&t); File: libc.info, Node: _go32_conventional_mem_selector, Next: _go32_dpmi_allocate_dos_memory, Prev: gmtime, Up: Alphabetical List _go32_conventional_mem_selector =============================== Syntax ------ #include <go32.h> u_short _go32_conventional_mem_selector(); Description ----------- This function returns a selector which has a physical base address corresponding to the beginning of conventional memory. This selector can be used as a parameter to `movedata' (*note movedata::.) to manipulate memory in the conventional address space. Return Value ------------ The selector. Portability ----------- not ANSI, not POSIX Example ------- short blank_row_buf[ScreenCols()]; /* scroll screen */ movedata(_go32_conventional_mem_selector(), 0xb8000 + ScreenCols()*2, _go32_conventional_mem_selector(), 0xb8000, ScreenCols() * (ScreenRows()-1) * 2); /* fill last row */ movedata(_go32_my_ds, (int)blank_row_buf, _go32_conventional_mem_selector(), 0xb8000 + ScreenCols()*(ScreenRows()-1)*2, ScreenCols() * 2); File: libc.info, Node: _go32_dpmi_allocate_dos_memory, Next: _go32_dpmi_allocate_iret_wrapper, Prev: _go32_conventional_mem_selector, Up: Alphabetical List _go32_dpmi_allocate_dos_memory ============================== Syntax ------ #include <dpmi.h> int _go32_dpmi_allocate_dos_memory(_go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. Allocate a part of the conventional memory area (the first 640K). Set the `size' field of INFO to the number of paragraphs requested (this is (size in bytes + 15)/16), then call. The `rm_segment' field of INFO contains the segment of the allocated memory. The memory may be resized with `_go32_dpmi_resize_dos_memory' and must be freed with `_go32_dpmi_free_dos_memory'. If there isn't enough memory in the system, the `size' field of INFO has the largest available size, and an error is returned. See also *Note dosmemput::, and *Note dosmemget::. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- _go32_dpmi_seginfo info; info.size = (want_size+15) / 16; _go32_dpmi_allocate_dos_memory(&info); dosmemput(buffer, want_size, info.rm_segment*16); _go32_dpmi_free_dos_memory(&info); File: libc.info, Node: _go32_dpmi_allocate_iret_wrapper, Next: _go32_dpmi_allocate_real_mode_callback_iret, Prev: _go32_dpmi_allocate_dos_memory, Up: Alphabetical List _go32_dpmi_allocate_iret_wrapper ================================ Syntax ------ #include <dpmi.h> int _go32_dpmi_allocate_iret_wrapper(_go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function creates a small assembler function that handles the overhead of servicing an interrupt. To use, put the address of your servicing function in the `pm_offset' field of INFO and call this function. The `pm_field' will get replaced with the address of the wrapper function, which you pass to both `_go32_dpmi_set_protected_mode_interrupt_vector' and `_go32_dpmi_free_iret_wrapper'. See also *Note _go32_dpmi_set_protected_mode_interrupt_vector::, and *Note _go32_dpmi_free_iret_wrapper::. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- _go32_dpmi_seginfo info; info.pm_offset = my_handler; _go32_dpmi_allocate_iret_wrapper(&info); _go32_dpmi_set_protected_mode_interrupt_handler(0x75, &info); ... _go32_dpmi_free_iret_wrapper(&info); File: libc.info, Node: _go32_dpmi_allocate_real_mode_callback_iret, Next: _go32_dpmi_allocate_real_mode_callback_retf, Prev: _go32_dpmi_allocate_iret_wrapper, Up: Alphabetical List _go32_dpmi_allocate_real_mode_callback_iret =========================================== Syntax ------ #include <dpmi.h> int _go32_dpmi_allocate_real_mode_callback_iret(_go32_dpmi_seginfo *info, _go32_dpmi_registers *regs); Description ----------- *Note DPMI Overview::. This function allocates a "real-mode callback". Fill in the `pm_offset' field of INFO and call this function. It will fill in the `rm_segment' and `rm_offset' fields. Any time a real-mode program calls the real-mode address, your function gets called. The registers in effect will be stored in REGS, which should be a global, and will be passed to your function. Any changes in REGS will be reflected back into real mode. A wrapper will be added to your function to simulate the effects of an `iret' instruction, so this function is useful for trapping real-mode software interrupts (like 0x1b - `Ctrl-<Break>' hit). Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- _go32_dpmi_registers regs; my_handler(_go32_dpmi_registers *r) { r->d.eax = 4; } setup() { _go32_dpmi_seginfo info; _go32_dpmi_seginfo old_vector; _go32_dpmi_get_real_mode_interrupt_vector(0x84, &old_vector); info.pm_offset = my_handler; _go32_dpmi_allocate_real_mode_callback_iret(&info, ®s); _go32_dpmi_set_real_mode_interrupt_vector(0x84, &info); do_stuff(); _go32_dpmi_set_real_mode_interrupt_vector(0x84, &old_vector); _go32_dpmi_free_real_mode_callback(&info); } File: libc.info, Node: _go32_dpmi_allocate_real_mode_callback_retf, Next: _go32_dpmi_chain_protected_mode_interrupt_vector, Prev: _go32_dpmi_allocate_real_mode_callback_iret, Up: Alphabetical List _go32_dpmi_allocate_real_mode_callback_retf =========================================== Syntax ------ #include <dpmi.h> int _go32_dpmi_allocate_real_mode_callback_retf(_go32_dpmi_seginfo *info, _go32_dpmi_registers *regs); Description ----------- *Note DPMI Overview::. This function allocates a "real-mode callback". Fill in the `pm_offset' field of INFO and call this function. It will fill in the `rm_segment' and `rm_offset' fields. Any time a real-mode program calls the real-mode address, your function gets called. The registers in effect will be stored in REGS, which should be a global, and will be passed to your function. Any changes in REGS will be reflected back into real mode. A wrapper will be added to your function to simulate the effects of a far return, such as the callback for the packet driver receiver. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- *Note _go32_dpmi_allocate_real_mode_callback_iret::, for an example of usage. File: libc.info, Node: _go32_dpmi_chain_protected_mode_interrupt_vector, Next: _go32_dpmi_free_dos_memory, Prev: _go32_dpmi_allocate_real_mode_callback_retf, Up: Alphabetical List _go32_dpmi_chain_protected_mode_interrupt_vector ================================================ Syntax ------ #include <dpmi.h> int _go32_dpmi_chain_protected_mode_interrupt_vector(int vector, _go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function is used to chain a protected mode interrupt. It will build a suitable wrapper that will call your function and then jump to the next handler. Your function need not perform any special handling. *Warning!* Because of the way DPMI works, you may *not* `longjmp' out of an interrupt handler or perform any system calls (such as `printf') from within an interrupt handler. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- *Note _go32_dpmi_set_protected_mode_interrupt_vector::. File: libc.info, Node: _go32_dpmi_free_dos_memory, Next: _go32_dpmi_free_iret_wrapper, Prev: _go32_dpmi_chain_protected_mode_interrupt_vector, Up: Alphabetical List _go32_dpmi_free_dos_memory ========================== Syntax ------ #include <dpmi.h> int _go32_dpmi_free_dos_memory(_go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function frees the conventional memory allocated by `_go32_dpmi_allocate_real_mode_memory'. You should pass it the same structure as was used to allocate it. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- _go32_dpmi_seginfo info; info.size = 100; _go32_dpmi_allocate_dos_memory(&info); _go32_dpmi_free_dos_memory(&info); File: libc.info, Node: _go32_dpmi_free_iret_wrapper, Next: _go32_dpmi_free_real_mode_callback, Prev: _go32_dpmi_free_dos_memory, Up: Alphabetical List _go32_dpmi_free_iret_wrapper ============================ Syntax ------ #include <dpmi.h> int _go32_dpmi_free_iret_wrapper(_go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function frees the memory used by the wrapper created by `_go32_dpmi_allocate_iret_wrapper'. You should not free a wrapper that is still in use. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- *Note _go32_dpmi_allocate_iret_wrapper::. File: libc.info, Node: _go32_dpmi_free_real_mode_callback, Next: _go32_dpmi_get_free_memory_information, Prev: _go32_dpmi_free_iret_wrapper, Up: Alphabetical List _go32_dpmi_free_real_mode_callback ================================== Syntax ------ #include <dpmi.h> int _go32_dpmi_free_real_mode_callback(_go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function frees the real-mode callbacks and wrappers allocated by `_go32_dpmi_allocate_real_mode_callback_iret' and `_go32_dpmi_allocate_real_mode_callback_retf'. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- *Note _go32_dpmi_allocate_real_mode_callback_iret::, for an example of usage. File: libc.info, Node: _go32_dpmi_get_free_memory_information, Next: _go32_dpmi_get_protected_mode_interrupt_vector, Prev: _go32_dpmi_free_real_mode_callback, Up: Alphabetical List _go32_dpmi_get_free_memory_information ====================================== Syntax ------ #include <dpmi.h int _go32_dpmi_get_free_memory_information(_go32_dpmi_meminfo *info); Description ----------- This function fills in the following structure: typedef struct { u_long available_memory; u_long available_pages; u_long available_lockable_pages; u_long linear_space; u_long unlocked_pages; u_long available_physical_pages; u_long total_physical_pages; u_long free_linear_space; u_long max_pages_in_paging_file; u_long reserved[3]; } _go32_dpmi_meminfo; The only field that is guaranteed to have useful data is `available_memory'. Any unavailable field has -1 in it. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- int phys_mem_left() { _go32_dpmi_meminfo info; _go32_dpmi_get_free_memory_information(&info); if (info.available_physical_pages != -1) return info.available_physical_pages * 4096; return info.available_memory; } File: libc.info, Node: _go32_dpmi_get_protected_mode_interrupt_vector, Next: _go32_dpmi_get_real_mode_interrupt_vector, Prev: _go32_dpmi_get_free_memory_information, Up: Alphabetical List _go32_dpmi_get_protected_mode_interrupt_vector ============================================== Syntax ------ #include <dpmi.h> int _go32_dpmi_get_protected_mode_interrupt_vector(int vector, _go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function puts the selector and offset of the specified interrupt vector into the `pm_selector' and `pm_offset' fields of INFO. This structure can be saved and later passed to `_go32_dpmi_get_protected_mode_interrupt_vector' to restore a vector. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- *Note _go32_dpmi_set_protected_mode_interrupt_vector::, for an example of usage. File: libc.info, Node: _go32_dpmi_get_real_mode_interrupt_vector, Next: _go32_dpmi_lock_code, Prev: _go32_dpmi_get_protected_mode_interrupt_vector, Up: Alphabetical List _go32_dpmi_get_real_mode_interrupt_vector ========================================= Syntax ------ #include <dpmi.h> int _go32_dpmi_get_real_mode_interrupt_vector(int vector, _go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function gets the real-mode interrupt vector specified into the address in the `rm_segment' and `rm_offset' fields in INFO. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- *Note _go32_dpmi_allocate_real_mode_callback_iret::, for an example of usage. File: libc.info, Node: _go32_dpmi_lock_code, Next: _go32_dpmi_lock_data, Prev: _go32_dpmi_get_real_mode_interrupt_vector, Up: Alphabetical List _go32_dpmi_lock_code ==================== Syntax ------ #include <dpmi.h> int _go32_dpmi_lock_code( void *lockaddr, unsigned long locksize); Description ----------- Locks the given region of code, starting at LOCKADDR for LOCKSIZE bytes. LOCKADDR is a regular pointer in your program, such as the address of a function. Return Value ------------ 0 if success, -1 if failure. Portability ----------- not ANSI, not POSIX Example ------- void my_handler() { } void lock_my_handler() { _go32_dpmi_lock_code(my_handler, (unsigned long)(lock_my_handler - my_handler)); } File: libc.info, Node: _go32_dpmi_lock_data, Next: _go32_dpmi_remaining_physical_memory, Prev: _go32_dpmi_lock_code, Up: Alphabetical List _go32_dpmi_lock_data ==================== Syntax ------ #include <dpmi.h> int _go32_dpmi_lock_data( void *lockaddr, unsigned long locksize); Description ----------- Locks the given region of data, starting at LOCKADDR for LOCKSIZE bytes. LOCKADDR is a regular pointer in your program, such as the address of a variable. Return Value ------------ 0 if success, -1 if failure. Portability ----------- not ANSI, not POSIX Example ------- int semaphore=0; void lock_my_handler() { _go32_dpmi_lock_data(&semaphore, 4); } File: libc.info, Node: _go32_dpmi_remaining_physical_memory, Next: _go32_dpmi_remaining_virtual_memory, Prev: _go32_dpmi_lock_data, Up: Alphabetical List _go32_dpmi_remaining_physical_memory ==================================== Syntax ------ #include <dpmi.h> unsigned long _go32_dpmi_remaining_physical_memory(void); Description ----------- Returns the amount of physical memory that is still available in the system. Return Value ------------ The amount in bytes. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _go32_dpmi_remaining_virtual_memory, Next: _go32_dpmi_resize_dos_memory, Prev: _go32_dpmi_remaining_physical_memory, Up: Alphabetical List _go32_dpmi_remaining_virtual_memory =================================== Syntax ------ #include <dpmi.h> unsigned long _go32_dpmi_remaining_virtual_memory(void); Description ----------- Returns the amount of virtual memory that is still available in the system. Return Value ------------ The amount in bytes. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _go32_dpmi_resize_dos_memory, Next: _go32_dpmi_set_protected_mode_interrupt_vector, Prev: _go32_dpmi_remaining_virtual_memory, Up: Alphabetical List _go32_dpmi_resize_dos_memory ============================ Syntax ------ #include <dpmi.h> int _go32_dpmi_resize_dos_memory(_go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. The INFO structure is the same one used to allocate the memory. Fill in a new value for `size' and call this function. If there is not enough memory to satisfy the request, the largest size is filled in to the `size' field, the memory is not resized, and this function fails. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- _go32_dpmi_seginfo info; info.size = 10; _go32_dpmi_allocate_dos_memory(&info); info.size = 20; _go32_dpmi_resize_dos_memory(&info); _go32_dpmi_free_dos_memory(&info); File: libc.info, Node: _go32_dpmi_set_protected_mode_interrupt_vector, Next: _go32_dpmi_set_real_mode_interrupt_vector, Prev: _go32_dpmi_resize_dos_memory, Up: Alphabetical List _go32_dpmi_set_protected_mode_interrupt_vector ============================================== Syntax ------ #include <dpmi.h> int _go32_dpmi_set_protected_mode_interrupt_vector(int vector, _go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function sets the protected mode interrupt vector specified to point to the given function. The `pm_offset' and `pm_selector' fields of INFO must be filled in (*note _go32_my_cs::.). The following should be noted: * You may not `longjmp' out of an interrupt handler. * You may not make any function calls that require system calls, such as `printf'. * This function will not wrap the handler for you. The `_go32_dpmi_allocate_iret_wrapper' and `_go32_dpmi_chain_protected_mode_interrupt_vector' functions can wrap your function if you want. * You must set the pm_selector field of INFO. Use `_go32_my_cs' to get a selector valid for your functions. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- volatile int tics = 0; timer_handler() { tics++; } int main() { _go32_dpmi_seginfo old_handler, new_handler; printf("grabbing timer interrupt\n"); _go32_dpmi_get_protected_mode_interrupt_vector(8, &old_handler); new_handler.pm_offset = (int)tic_handler; new_handler.pm_selector = _go32_my_cs(); _go32_dpmi_chain_protected_mode_interrupt_vector(8, &new_handler); getkey(); printf("releasing timer interrupt\n"); _go32_dpmi_set_protected_mode_interrupt_vector(8, &old_handler); return 0; } File: libc.info, Node: _go32_dpmi_set_real_mode_interrupt_vector, Next: _go32_dpmi_simulate_fcall, Prev: _go32_dpmi_set_protected_mode_interrupt_vector, Up: Alphabetical List _go32_dpmi_set_real_mode_interrupt_vector ========================================= Syntax ------ #include <dpmi.h> int _go32_dpmi_set_real_mode_interrupt_vector(int vector, _go32_dpmi_seginfo *info); Description ----------- *Note DPMI Overview::. This function sets the real-mode interrupt vector specified to point to the address in the `rm_segment' and `rm_offset' fields in INFO. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- *Note _go32_dpmi_allocate_real_mode_callback_iret::, for an example of usage. File: libc.info, Node: _go32_dpmi_simulate_fcall, Next: _go32_dpmi_simulate_fcall_iret, Prev: _go32_dpmi_set_real_mode_interrupt_vector, Up: Alphabetical List _go32_dpmi_simulate_fcall ========================= Syntax ------ #include <dpmi.h> int _go32_dpmi_simulate_fcall(_go32_dpmi_registers *regs); Description ----------- *Note DPMI Overview::. This function simulates a real-mode far call to a function that returns with a far return. The registers are set up from REGS, including `CS' and `IP', which indicate the address of the call. Any registers the function modifies are reflected in REGS on return. If `SS' and `SP' are both zero, a small temporary stack is used when in real mode. If not, they are used *as is*. It's a good idea to use `memset' to initialize the register structure before using it. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- _go32_dpmi_registers r; r.x.ax = 47; r.x.cs = some_segment; r.x.ip = some_offset; r.x.ss = r.x.sp = 0; _go32_dpmi_simulate_fcall(&r); printf("returns %d\n", r.x.ax); File: libc.info, Node: _go32_dpmi_simulate_fcall_iret, Next: _go32_dpmi_simulate_int, Prev: _go32_dpmi_simulate_fcall, Up: Alphabetical List _go32_dpmi_simulate_fcall_iret ============================== Syntax ------ #include <dpmi.h> int _go32_dpmi_simulate_fcall_iret(_go32_dpmi_registers *regs); Description ----------- *Note DPMI Overview::. This function simulates a real-mode far call to a function that returns with an `iret' instruction. The registers are set up from REGS, including `CS' and `IP', which indicate the address of the call. Any registers the function modifies are reflected in REGS on return. If `SS' and `SP' are both zero, a small temporary stack is used when in real mode. If not, they are used *as is*. It's a good idea to use `memset' to initialize the register structure before using it. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- _go32_dpmi_registers r; r.x.ax = 47; r.x.cs = some_segment; r.x.ip = some_offset; r.x.ss = r.x.sp = 0; _go32_dpmi_simulate_fcall_iret(&r); printf("returns %d\n", r.x.ax); File: libc.info, Node: _go32_dpmi_simulate_int, Next: _go32_info_block, Prev: _go32_dpmi_simulate_fcall_iret, Up: Alphabetical List _go32_dpmi_simulate_int ======================= Syntax ------ #include <dpmi.h> int _go32_dpmi_simulate_int(int vector, _go32_dpmi_registers *regs); Description ----------- *Note DPMI Overview::. This function simulates a real-mode interrup. The registers are set up from REGS, including `CS' and `IP', which indicate the address of the call. Any registers the function modifies are reflected in REGS on return. If `SS' and `SP' are both zero, a small temporary stack is used when in real mode. If not, they are used *as is*. It's a good idea to use `memset' to initialize the register structure before using it. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- _go32_dpmi_registers r; r.h.ah = 0x08; r.h.dl = 0x80; /* drive C: */ r.x.ss = r.x.sp = 0; _go32_dpmi_simulate_int(0x13, &r); printf("disk is %d cyl, %d head, %d sect\n", r.h.ch | ((r.x.cl<<2)&0x300), r.h.dh, r.h.cl & 0x3f)); File: libc.info, Node: _go32_info_block, Next: _go32_interrupt_stack_size, Prev: _go32_dpmi_simulate_int, Up: Alphabetical List _go32_info_block ================ Syntax ------ #include <go32.h> extern __Go32_Info_Block _go32_info_block; Description ----------- The go32 information block is a mechanism for `go32' to pass information to the application. Some of this information is generally useful, such as the pid or the transfer buffer, while some is used internally to `libc.a' only. The structure has this format: typedef struct { unsigned long size_of_this_structure_in_bytes; unsigned long linear_address_of_primary_screen; unsigned long linear_address_of_secondary_screen; unsigned long linear_address_of_transfer_buffer; unsigned long size_of_transfer_buffer; unsigned long pid; unsigned char master_interrupt_controller_base; unsigned char slave_interrupt_controller_base; unsigned short selector_for_linear_memory; unsigned long linear_address_of_stub_info_structure; unsigned long linear_address_of_original_psp; unsigned short run_mode; unsigned short run_mode_info; } Go32_Info_Block; The linear address fields provide values that are suitable for `dosmemget', `dosmemput', and `movedata'. The selector_for_linear_memory is suitable for `<sys/farptr.h>' selector parameters. Due to the length of these fields, and their popularity, the following macros are available: `_dos_ds' This expands to _go32_info_block.selector_for_linear_memory `__tb' This expands to _go32_info_block.linear_address_of_transfer_buffer The `run_mode' field indicates the mode that the program is running in. The following modes are defined: `_GO32_RUN_MODE_UNDEF' This indicates that the extender did not (or could not) determine or provide the mode information. The most probable reason is that it's an older extender that does not support this field. The program should not assume anything about the run mode if it is this value. `_GO32_RUN_MODE_RAW' This indicates that no CPU manager is being used, and no XMS manager is present. The CPU is being managed directly from the extender, and memory was allocated from the extended memory pool. `_GO32_RUN_MODE_XMS' This indicates that the extender is managing the CPU, but an XMS driver is managing the memory pool. `_GO32_RUN_MODE_VCPI' This indicates that a VCPI server (like `emm386' or `qemm') is managing both the CPU and the memory. `_GO32_RUN_MODE_DPMI' This indicates that a DPMI server (like `qdpmi' or Windows) is managing both the CPU and memory. Programs may rely on this value to determine if it is safe to use DPMI 0.9 functions. If this value is set, the `run_mode_info' field has the DPMI specification version, in hex, shifted eight bits. For example, DPMI 0.9 has 0x005A in the `run_mode_info' field. Note that the program should not assume that the value will be one of the listed values. If the program is running with an extender that provides some other mode (say, a newly released extender) then the program should be able to handle that case gracefully. Portability ----------- not ANSI, not POSIX Example ------- dosmemget(_go32_info_block.linear_address_of_primary_screen, 80*25*2, buf); File: libc.info, Node: _go32_interrupt_stack_size, Next: _go32_my_cs, Prev: _go32_info_block, Up: Alphabetical List _go32_interrupt_stack_size ========================== Syntax ------ #include <dpmi.h> extern unsigned long _go32_interrupt_stack_size; Description ----------- The default size of the interrupt handler's stack. Defaults to 32k. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _go32_my_cs, Next: _go32_my_ds, Prev: _go32_interrupt_stack_size, Up: Alphabetical List _go32_my_cs =========== Syntax ------ #include <go32.h> u_short _go32_my_cs(); Description ----------- Returns the current `CS'. This is useful for setting up interrupt vectors and such. Return Value ------------ `CS' Portability ----------- not ANSI, not POSIX File: libc.info, Node: _go32_my_ds, Next: _go32_my_ss, Prev: _go32_my_cs, Up: Alphabetical List _go32_my_ds =========== Syntax ------ #include <go32.h> u_short _go32_my_ds(); Description ----------- Returns the current `DS'. This is useful for moving memory and such. Return Value ------------ `DS' Portability ----------- not ANSI, not POSIX File: libc.info, Node: _go32_my_ss, Next: _go32_rmcb_stack_size, Prev: _go32_my_ds, Up: Alphabetical List _go32_my_ss =========== Syntax ------ #include <go32.h> u_short _go32_my_ss(); Description ----------- Returns the current `SS'. This is useful for moving memory and such. Return Value ------------ `SS' Portability ----------- not ANSI, not POSIX File: libc.info, Node: _go32_rmcb_stack_size, Next: _go32_want_ctrl_break, Prev: _go32_my_ss, Up: Alphabetical List _go32_rmcb_stack_size ===================== Syntax ------ #include <dpmi.h> extern unsigned long _go32_rmcb_stack_size; Description ----------- The default size of the real mode callback handler's stack. Defaults to 32k. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _go32_want_ctrl_break, Next: _go32_was_ctrl_break_hit, Prev: _go32_rmcb_stack_size, Up: Alphabetical List _go32_want_ctrl_break ===================== Syntax ------ #include <go32.h> void _go32_want_ctrl_break(int yes); Description ----------- This function tells go32 whether or not it wants `Ctrl-Break' to be an exception or passed to the application. If you pass a nonzero value for YES, pressing `Ctrl-Break' will set a flag that can be detected with `_go32_was_ctrl_break_hit' (*note _go32_was_ctrl_break_hit::.). If you pass zero for YES, when you press `Ctrl-Break' the program will be terminated. Note that if you call `_go32_was_ctrl_break_hit', this function automatically gets called to ask for `Ctrl-Break' events. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- _g32_want_ctrl_break(1); do_something_long(); _g32_want_ctrl_break(0); File: libc.info, Node: _go32_was_ctrl_break_hit, Next: gotoxy, Prev: _go32_want_ctrl_break, Up: Alphabetical List _go32_was_ctrl_break_hit ======================== Syntax ------ #include <go32.h> unsigned _go32_was_ctrl_break_hit(void); Description ----------- This function returns the number of times that `Ctrl-Break' was hit since the last call to this function or `_go32_want_ctrl_break' (*note _go32_want_ctrl_break::.). Return Value ------------ Zero if `Ctrl-Break' hasn't been hit, nonzero to indicate how many times if it has been hit. Note that `_go32_want_ctrl_break' is automatically called to request these events, so you don't have to set up for this call. Portability ----------- not ANSI, not POSIX Example ------- while (!_go32_was_ctrl_break_hit()) do_something(); File: libc.info, Node: gotoxy, Next: gppconio_init, Prev: _go32_was_ctrl_break_hit, Up: Alphabetical List gotoxy ====== Syntax ------ #include <conio.h> void gotoxy(int x, int y); Description ----------- Move the cursor to row y, column x. The upper left corner of the current window is (1,1). Portability ----------- not ANSI, not POSIX File: libc.info, Node: gppconio_init, Next: hasmntopt, Prev: gotoxy, Up: Alphabetical List gppconio_init ============= Syntax ------ #include <conio.h> void gppconio_init(void); Description ----------- Initialize the screen. This is called automatically at program start-up if you use any of the `conio' functions, but there may be times when you need to call it again, typically after calling some video BIOS function which affects screen parameters. Portability ----------- not ANSI, not POSIX File: libc.info, Node: hasmntopt, Next: highvideo, Prev: gppconio_init, Up: Alphabetical List hasmntopt ========= Syntax ------ #include <mntent.h> char *hasmntopt(const struct mntent *mnt, const char *opt); Description ----------- This function scans the `mnt_opts' field of the `mntent' structure pointed to by MNT for a substring that matches OPT. *Note getmntent::. Return Value ------------ This function returns the address of the substring if a match is found, or `NULL' otherwise. Portability ----------- not ANSI, not POSIX File: libc.info, Node: highvideo, Next: htonl, Prev: hasmntopt, Up: Alphabetical List highvideo ========= Syntax ------ #include <conio.h> void highvideo(void); Description ----------- Causes any new characters put on the screen to be bright. Portability ----------- not ANSI, not POSIX File: libc.info, Node: htonl, Next: htons, Prev: highvideo, Up: Alphabetical List htonl ===== Syntax ------ #include <netinet/in.h> unsigned long htonl(unsigned long val); Description ----------- This function converts from host formatted longs to network formatted longs. For the i386 and higher processors, this means that the bytes are swapped from 1234 order to 4321 order. Return Value ------------ The network-order value. Portability ----------- not ANSI, not POSIX Example ------- packet.ipaddr = htonl(ip); File: libc.info, Node: htons, Next: hypot, Prev: htonl, Up: Alphabetical List htons ===== Syntax ------ #include <netinet/in.h> unsigned short htons(unsigned short val); Description ----------- This function converts from host formatted shorts to network formatted shorts. For the i386 and higher processors, this means that the bytes are swapped from 12 order to 21 order. Return Value ------------ The network-order value. Portability ----------- not ANSI, not POSIX Example ------- tcp.port = htons(port); File: libc.info, Node: hypot, Next: inb, Prev: htons, Up: Alphabetical List hypot ===== Syntax ------ #include <math.h> double hypot(double x, double y); Description ----------- This function computes `sqrt(X*X + Y*Y)', the length of a hypotenuse of a right triangle whose shorter sides are X and Y. In other words, it computes the Euclidean distance between the points `(0,0)' and `(X,Y)'. Since the computation is done in extended precision, there is no danger of overflow or underflow when squaring the arguments, whereas direct computation of `sqrt(X*X + Y*Y)' could cause overflow or underflow for extreme (very large or very small) values of X and Y. Return Value ------------ The value of `sqrt(X*X + Y*Y)'. If both arguments are finite, but the result is so large that it would overflow a `double', the return value is `Inf', and `errno' is set to `ERANGE'. If one of the arguments is `Inf', the return value is `Inf' and the value of `errno' is left unchanged. If one of the arguments is `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inb, Next: index, Prev: hypot, Up: Alphabetical List inb === Syntax ------ #include <pc.h> unsigned char inb(unsigned short _port); Description ----------- Calls *Note inportb::. Provided only for compatibility. Portability ----------- not ANSI, not POSIX File: libc.info, Node: index, Next: initstate, Prev: inb, Up: Alphabetical List index ===== Syntax ------ #include <strings.h> char *index(const char *string, int ch); Description ----------- Returns a pointer to the first occurrence of CH in STRING. Note that the `NULL' character counts, so if you pass zero as CH you'll get a pointer to the end of the string back. Return Value ------------ A pointer to the character, or `NULL' if it wasn't found. Portability ----------- not ANSI, not POSIX Example ------- if (index(path, '*')) do_wildcards(path); File: libc.info, Node: initstate, Next: inp, Prev: index, Up: Alphabetical List initstate ========= Syntax ------ #include <stdlib.h> char *initstate(unsigned seed, char *arg_state, int n); Description ----------- Initializes the random number generator (*note random::.) with pointer ARG_STATE to array of N bytes, then calls `srandom' with SEED. Return Value ------------ Pointer to old state information. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inp, Next: inportb, Prev: initstate, Up: Alphabetical List inp === Syntax ------ #include <pc.h> unsigned char inp(unsigned short _port); Description ----------- Calls *Note inportb::. Provided only for compatibility. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inportb, Next: inportl, Prev: inp, Up: Alphabetical List inportb ======= Syntax ------ #include <pc.h> unsigned char inportb(unsigned short _port); Description ----------- Read a single 8-bit I/O port. This function is provided as an inline assembler macro, and will be optimized down to a single opcode when you optimize your program. Return Value ------------ The value returned through the port. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inportl, Next: inportsb, Prev: inportb, Up: Alphabetical List inportl ======= Syntax ------ #include <pc.h> unsigned long inportl(unsigned short _port); Description ----------- This function reads a single 32-bit I/O port. This function is provided as an inline assembler macro, and will be optimized down to a single opcode when you optimize your program. Return Value ------------ The value returned from the port. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inportsb, Next: inportsl, Prev: inportl, Up: Alphabetical List inportsb ======== Syntax ------ #include <pc.h> void inportsb(unsigned short _port, unsigned char *_buf, unsigned _len); Description ----------- Reads the 8-bit _PORT _LEN times, and stores the bytes in BUF. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inportsl, Next: inportsw, Prev: inportsb, Up: Alphabetical List inportsl ======== Syntax ------ #include <pc.h> void inportsl(unsigned short _port, unsigned long *_buf, unsigned _len); Description ----------- Reads the 32-bit _PORT _LEN times, and stores the bytes in BUF. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inportsw, Next: inportw, Prev: inportsl, Up: Alphabetical List inportsw ======== Syntax ------ #include <pc.h> void inportsw(unsigned short _port, unsigned short *_buf, unsigned _len); Description ----------- Reads the 16-bit _PORT _LEN times, and stores the bytes in BUF. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inportw, Next: inpw, Prev: inportsw, Up: Alphabetical List inportw ======= Syntax ------ #include <pc.h> unsigned short inportw(unsigned short _port); Description ----------- Read a single 16-bit I/O port. This function is provided as an inline assembler macro, and will be optimized down to a single opcode when you optimize your program. Return Value ------------ The value returned through the port. Portability ----------- not ANSI, not POSIX File: libc.info, Node: inpw, Next: insline, Prev: inportw, Up: Alphabetical List inpw ==== Syntax ------ #include <pc.h> unsigned short inpw(unsigned short _port); Description ----------- Calls *Note inportw::. Provided only for compatibility. Portability ----------- not ANSI, not POSIX File: libc.info, Node: insline, Next: insque, Prev: inpw, Up: Alphabetical List insline ======= Syntax ------ #include <conio.h> void insline(void); Description ----------- A blank line is inserted at the current cursor position. The previous line and lines below it scroll down. Portability ----------- not ANSI, not POSIX File: libc.info, Node: insque, Next: int386, Prev: insline, Up: Alphabetical List insque ====== Syntax ------ #include <search.h> void insque(struct qelem *elem, struct qelem *pred); Description ----------- This function manipulates queues built from doubly linked lists. Each element in the queue must be in the form of `struct qelem' which is defined thus: struct qelem { struct qelem *q_forw; struct qelem *q_back; char q_data[0]; } This function inserts ELEM in a queue immediately after PRED. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: int386, Next: int386x, Prev: insque, Up: Alphabetical List int386 ====== Syntax ------ #include <dos.h> int int386(int ivec, union REGS *in, union REGS *out); Description ----------- This function is equal to `int86' function. See *Note int86::, for further description. Return Value ------------ The returned value of `EAX'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: int386x, Next: int86, Prev: int386, Up: Alphabetical List int386x ======= Syntax ------ #include <dos.h> int int386x(int ivec, union REGS *in, union REGS *out, struct SREGS *seg); Description ----------- This function is equal to `int86x'. See *Note int86::, for further description. Return Value ------------ The value of `EAX' is returned. Portability ----------- not ANSI, not POSIX File: libc.info, Node: int86, Next: int86x, Prev: int386x, Up: Alphabetical List int86 ===== Syntax ------ #include <dos.h> int int86(int ivec, union REGS *in, union REGS *out); Description ----------- The `union REGS' is defined by `<dos.h>' as follows: struct DWORDREGS { unsigned long edi; unsigned long esi; unsigned long ebp; unsigned long cflag; unsigned long ebx; unsigned long edx; unsigned long ecx; unsigned long eax; unsigned short eflags; }; struct DWORDREGS_W { unsigned long di; unsigned long si; unsigned long bp; unsigned long cflag; unsigned long bx; unsigned long dx; unsigned long cx; unsigned long ax; unsigned short flags; }; struct WORDREGS { unsigned short di, _upper_di; unsigned short si, _upper_si; unsigned short bp, _upper_bp; unsigned short cflag, _upper_cflag; unsigned short bx, _upper_bx; unsigned short dx, _upper_dx; unsigned short cx, _upper_cx; unsigned short ax, _upper_ax; unsigned short flags; }; struct BYTEREGS { unsigned short di, _upper_di; unsigned short si, _upper_si; unsigned short bp, _upper_bp; unsigned long cflag; unsigned char bl; unsigned char bh; unsigned short _upper_bx; unsigned char dl; unsigned char dh; unsigned short _upper_dx; unsigned char cl; unsigned char ch; unsigned short _upper_cx; unsigned char al; unsigned char ah; unsigned short _upper_ax; unsigned short flags; }; union REGS { struct DWORDREGS d; #ifdef _NAIVE_DOS_REGS struct WORDREGS x; #else #ifdef _BORLAND_DOS_REGS struct DWORDREGS x; #else struct DWORDREGS_W x; #endif #endif struct WORDREGS w; struct BYTEREGS h; }; Note: The `.x.' branch is a problem generator. Most programs expect the `.x.' branch to have e.g. "`.x.ax'" members, and that they are 16-bit. If you know you want 32-bit values, use the `.d.eax' members. If you know you want 16-bit values, use the `.w.ax' members. The `.x.' members behave according to `#defines', as follows: `default' If you specify no `#define', the `.x.' branch has "`ax'" members and is 32-bit. This is compatible with previous versions of djgpp. `_NAIVE_DOS_REGS' This define gives you `.x.ax', but they are 16-bit. This is probably what most programs ported from 16-bit dos compilers will want. `_BORLAND_DOS_REGS' This define gives you `.x.eax' which are 32-bit. This is compatible with Borland's 32-bit compilers. This function simulates a software interrupt. Note that, unlike the `__dpmi_int' function, requests that go through `int86' and similar functions are specially processed to make them suitable for invoking real-mode interrupts from protected-mode programs. For example, if a particular routine takes a pointer in `BX', `int86' expects you to put a (protected-mode) pointer in `EBX'. Therefore, `int86' should have specific support for every interrupt and function you invoke this way. Currently, it supports only a subset of all available interrupts and functions: 1) All functions of any interrupt which expects only scalar arguments registers (i.e., no pointers to buffers). 2) In addition, the following functions of interrupt 21h are supported: 9, 39h, 3Ah, 3Bh, 3Ch, 3Dh, 3Fh, 40h, 41h, 43h, 47h, 56h. When the interrupt is invoked, the CPU registers are copied from IN. After the interrupt, the CPU registers are copied to OUT. This function is just like `int86x' (*note int86x::.) except that suitable default values are used for the segment registers. See also *Note int86x::, *Note intdos::, and *Note bdos::. Return Value ------------ The returned value of `EAX'. Portability ----------- not ANSI, not POSIX Example ------- union REGS r; r.x.ax = 0x0100; r.h.dl = 'c'; int86(0x21, &r, &r); File: libc.info, Node: int86x, Next: intdos, Prev: int86, Up: Alphabetical List int86x ====== Syntax ------ #include <dos.h> int int86x(int ivec, union REGS *in, union REGS *out, struct SREGS *seg); Description ----------- This function is just like `int86' (*note int86::.) except that values you pass in SREGS are used for the segment registers instead of the defaults. See also *Note int86::, *Note intdos::, and *Note bdos::. Return Value ------------ The value of `EAX' is returned. Portability ----------- not ANSI, not POSIX Example ------- union REGS r; struct SREGS s; r.h.ah = 0x31; r.h.dl = 'c'; r.x.si = si_val; s.ds = ds_val; int86x(0x21, &r, &r, &s); File: libc.info, Node: intdos, Next: intdosx, Prev: int86x, Up: Alphabetical List intdos ====== Syntax ------ #include <dos.h> int intdos(union REGS *in, union REGS *out); Description ----------- This function is just like `int86' (*note int86x::.) except that the interrupt vector is 0x21. Return Value ------------ `EAX' Portability ----------- not ANSI, not POSIX File: libc.info, Node: intdosx, Next: intensevideo, Prev: intdos, Up: Alphabetical List intdosx ======= Syntax ------ #include <dos.h> int intdosx(union REGS *in, union REGS *out, struct SREGS *s); Description ----------- This function is just like `int86x' (*note int86x::.) except that the interrupt vector is 0x21. Return Value ------------ `EAX' Portability ----------- not ANSI, not POSIX File: libc.info, Node: intensevideo, Next: _invent_inode, Prev: intdosx, Up: Alphabetical List intensevideo ============ Syntax ------ #include <conio.h> void intensevideo(void); Description ----------- Bit 7 (`MSB') of the character attribute byte has two possible effects on EGA and VGA displays: it can either make the character blink or change the background color to bright (thus allowing for 16 background colors as opposed to the usual 8). This function sets that bit to display bright background colors. After a call to this function, every character written to the screen with bit 7 of the attribute byte set, will have a bright background color. The companion function `blinkvideo' (*note blinkvideo::.) has the opposite effect. Note that there is no BIOS function to get the current status of this bit, but bit 5 of the byte at `0040h:0065h' in the BIOS area indicates the current state: if it's 1 (the default), blinking characters will be displayed. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _invent_inode, Next: ioctl (DOS), Prev: intensevideo, Up: Alphabetical List _invent_inode ============= Syntax ------ ino_t _invent_inode(const char *name, unsigned time_stamp, unsigned long fsize) Description ----------- This invents an inode number for those files which don't have valid DOS cluster number. These could be: * devices like `/dev/null' or file system extensions (*note File System Extensions::.) * empty files which were not allocated disk space yet * or files on networked drives, for which the redirector doesn't bring the cluster number. To ensure proper operation of this function, you must call it with a filename in some canonical form. E.g., with a name returned by `truename()' (*note _truename::.), or that returned by `_fixpath()' (*note _fixpath::.). The point here is that the entire program *must* abide by these conventions through its operation, or else you risk getting different inode numbers for the same file. Return Value ------------ 0 on error, otherwise the invented inode number for the file Portability ----------- not ANSI, not POSIX File: libc.info, Node: ioctl (DOS), Next: ioctl (General description), Prev: _invent_inode, Up: Alphabetical List ioctl (DOS) =========== The DOSish version of `ioctl' performs an interrupt 0x21, function 0x44. It takes care of supplying transfer buffers in low address regions, if they are needed. For an exhaustive description of the various commands and subcommands, see Ralf Brown's interrupt list. It is highly recommended to use only the DOS_* functions listed in `sys/ioctl.h'. Syntax ------ #include <sys/ioctl.h> int ioctl(int fd, int cmd, ... ); Description ----------- The parameter `fd' must refer to a file descriptor for character device functions, or the number of a block device (usually current=0, A:=1, ...). The following constants can be used for the `cmd' parameter: `DOS_GETDEVDATA' Get device information. Returns the device information word from `DX'. The call to `ioctl' should look like this: int ret_val = ioctl (fd, DOS_GETDEVDATA); For another way of achieving the same effect, see *Note _get_dev_info::. `DOS_SETDEVDATA' Set device information. Returns the new device information word form `DX' or -1. The call to `ioctl' should look like this: int ret_val = ioctl (fd, DOS_SETDEVDATA, 0, dev_info); `DOS_RCVDATA' Read from character device control channel. After `cmd' must follow the number of requested bytes to read and a pointer to a buffer. Returns the number of bytes actually read or -1 on error. The call to `ioctl' should look like this: unsigned char buf[bytes_to_read]; int ret_val = ioctl (fd, DOS_RCVDATA, bytes_to_read, &buf); `DOS_SNDDATA' Write to character device control channel. After `cmd' must follow the number of bytes to write and a pointer to a buffer holding the data. Returns the number of bytes actually written. An example of a call: unsigned char buf[bytes_to_write]; int ret_val = ioctl (fd, DOS_SNDDATA, bytes_to_write, &buf); `DOS_RCVCTLDATA' Read from block device control channel. See `DOS_RCVDATA'. `DOS_SNDCTLDATA' Write to block device control channel. See `DOS_SNDDATA'. `DOS_CHKINSTAT' Check the input status of a file. Returns 0 if not ready of at EOF, `0xff' if file is ready. Here's an example of how to call: int ret_val = ioctl (fd, DOS_CHKINSTAT); A more portable way of doing this is by calling `select'. *Note select::. `DOS_CHKOUTSTAT' Check the output status of a file. Returns 0 if not ready of at EOF, `0xff' if file is ready. `select' (*note select::.) is another, more portable way of doing the same. `DOS_ISCHANGEABLE' Check if a block device is changeable. Returns 0 for removable or 1 for fixed. An example of a call: int ret_val = ioctl (fd, DOS_ISCHANGEABLE); `DOS_ISREDIRBLK' Check if a block device is remote o local. The function `_is_remote_drive' (*note _is_remote_drive::.) is another way of returning the same info. `DOS_ISREDIRHND' Check if a file handle refers to a local or remote device. See *Note _is_remote_handle:: for another way of doing this. `DOS_SETRETRY' Set the sharing retry count. The first extra parameter specifies the pause between retries, the second number of retries. An example: int ret_val = ioctl (fd, DOS_SETRETRY, pause_between_retries, max_retries); `DOS_GENCHARREQ' Generic character device request. Example: int ret_val = ioctl (fd, DOS_GENCHARREQ, category_and_function, ¶m_block, si_value, di_value, param_block_size); Refer to Ralf Brown's Interrupt List for the details about each function and relevant parameter block layout. `DOS_GENBLKREQ' Generic block device request. Example of the call: int ret_val = ioctl (drive_no, DOS_GENBLKREQ, category_and_function, ¶m_block, si_value, di_value, param_block_size); Note that instead of the handle, the first argument is the disk drive number (0 = default, 1 = A:, etc.). `DOS_GLDRVMAP' Get logical drive map. A call like the following: int ret_val = ioctl (drive_no, DOS_GLDRVMAP); will return 0 if the block device has only one logical drive assigned, or a number in the range 1..26 which is the last drive numer used to reference that drive (1 = A:, etc.). Thus, on a machine which has a single floppy drive, calling `ioctl (1, DOS_GLDRVMAP);' will return 2 if the floppy was last refered to as B:. This function and the next one can be used together to prevent DOS from popping the ugly prompt saying "Insert diskette for drive B: and press any key when ready". `DOS_SLDRVMAP' Set logical drive map. For example, a call like this: ioctl (1, DOS_SLDRVMAP); will cause drive A: to be mapped to drive B:. `DOS_QGIOCTLCAPH' Query generic ioctl capability (handle). Test if a handle supports ioctl functions beyond those in the standard DOS 3.2 set. Call like this: int ret_val = ioctl (fd, DOS_QGIOCTLCAPH, category_and_function); This will return zero if the specified IOCTL function is supported, 1 if not. `DOS_QGIOCTLCAPD' Query generic ioctl capability (drive). Test if a drive supports ioctl functions beyond those in the standard DOS 3.2 set. Used same as DOS_QGIOCTLCAPH, but the first argument is a drive number (0 = default, 1 = A:, etc.), not a handle. If your specific device driver requires different commands, they must be or'ed together with the flags listed in `<sys/ioctl.h>' to tell the drive about transfer buffers and what to return. Return Value ------------ See description above. Device information word ----------------------- The bits of the device information word have the following meaning:\\ Character device: 14 Device driver can process IOCTL request 13 output until busy supported 11 driver supports OPEN/CLOSE calls 7 set (indicates device) 6 EOF on input 5 raw (binary) mode 4 device is special (uses INT 29) 3 clock device 2 NUL device 1 standard output 0 standard input Disk file: 15 file is remote (DOS 3.0+) 14 don't set file date/time on closing (DOS 3.0+) 11 media not removable 8 (DOS 4 only) generate INT 24 if no disk space on write or read past end of file 7 clear (indicates file) 6 file has not been written 5-0 drive number (0 = A:) Example ------- #include <sys/ioctl.h> int main(int argc, char **argv){ char buf[6]; short *s; open(fd,"EMMQXXX0",O_RDONLY); mybuf[0] = '\0'; s = mybuf; ioctl(fd,DOS_SNDDATA,6, (int) &mybuf); if(*s ==0x25 )printf("EMM386 >= 4.45\n"); mybuf[0]='\x02'; ioctl(fd,DOS_SNDDATA,2,(int )&mybuf); printf("EMM Version %d.%d\n",(int )mybuf[0],(int) mybuf[1]); close(fd); } File: libc.info, Node: ioctl (General description), Next: ioctl (UNIX), Prev: ioctl (DOS), Up: Alphabetical List ioctl (General description) =========================== `ioctl' performs low level calls to communicate with device drivers. As there are lots of different device drivers, no really general description is possible. The DJGPP version tries to cope with two different flavors of `ioctl', a DOSish and a UNIXish way. To distinguish between DOS-like and UNIX-like calls, all valid DOS commands have all 3 MSB set to 0, the UNIX command have at least one of the 3 MSB set to 1. File: libc.info, Node: ioctl (UNIX), Next: _is_executable, Prev: ioctl (General description), Up: Alphabetical List ioctl (UNIX) ============ The UNIX version first checks if an FSE handler is associated to the file descriptor. If so, it calls the handler in the usual way *Note File System Extensions::. Otherwise it sets ERRNO to `ENOTTY' and returns -1. As this part is still under development, it should not be used exhaustively. File: libc.info, Node: _is_executable, Next: _is_remote_drive, Prev: ioctl (UNIX), Up: Alphabetical List _is_executable ============== Syntax ------ #include <sys/stat.h> int _is_executable(const char *path, int fhandle, const char *extension); Description ----------- This function determines if a file is executable under DOS/DJGPP environment. The file may be given either by its PATH or its file handle FHANDLE. If EXTENSION is non-NULL and non-empty, it is used first to look up in a list of known extensions which determine whether the file is executable. (If the `_STAT_EXEC_EXT' bit of the `_djstat_flags' global variable (*note _djstat_flags::.) is not set, this step is skipped.) If EXTENSION is unavailable or not enough to determine the result, the first 2 bytes of the file are checked to contain one of the known `magic numbers' identifying the file as executable. If the file's 2 first bytes need to be read but the read fails, 0 is returned and errno is set. (The file is only searched for magic number if the `_STAT_EXEC_MAGIC' bit of the `_djstat_flags' variable is set.) Note that if `_STAT_EXEC_MAGIC' is set, but `_STAT_EXEC_EXT' is not, some files which shouldn't be flagged as executables (e.g., COFF `*.o' object files) will have their execute bit set, because they have the magic number signature at their beginning. Therefore, only use the above combination if you want to debug the list of extensions provided in `is_exec.c' file from the library sources. If the file passed by its handle was open as write-only, and the extension alone isn't enough to determine whether the file is executable, then this function returns 0, because it cannot look at the `magic number'. This function is used internally by `f?stat'; you are not supposed to call it directly. Return Value ------------ 1 for executable file, 0 otherwise (including in case of errors in accessing the file). Portability ----------- not ANSI, not POSIX File: libc.info, Node: _is_remote_drive, Next: _is_remote_handle, Prev: _is_executable, Up: Alphabetical List _is_remote_drive ================ Syntax ------ int _is_remote_drive(int drv); Description ----------- Given the drive number in DRV (A: = 0, B: = 1, etc.), this function returns non-zero if the drive is treated by DOS as a remote (networked) drive, or zero otherwise. It does so by calling subfunction 09h of the DOS IOCTL function (interrupt 21h, AX=4409h) and looking at bit 12 of the device attribute word returned in the DX register. Note that DOS treats CD-ROM drives as remote. Return Value ------------ Zero for local drives, non-zero for remote and CD-ROM drives. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _is_remote_handle, Next: isalnum, Prev: _is_remote_drive, Up: Alphabetical List _is_remote_handle ================= Syntax ------ int _is_remote_handle(int fhandle); Description ----------- Given the file handle of an open file in FHANDLE, this function returns non-zero if the drive where that file resides is treated by DOS as a remote (networked) drive, or zero otherwise. It does so by calling subfunction 0Ah of the DOS IOCTL function (interrupt 21h, AX=440Ah) and looking at bit 15 of the device attribute word returned in the DX register. Note that DOS treats CD-ROM drives as remote. Return Value ------------ Zero for files on local drives, non-zero for files on remote and CD-ROM drives. Portability ----------- not ANSI, not POSIX File: libc.info, Node: isalnum, Next: isalpha, Prev: _is_remote_handle, Up: Alphabetical List isalnum ======= Syntax ------ #include <ctype.h> int isalnum(int c); Description ----------- Tells if C is any letter or digit. Return Value ------------ Nonzero if C is a letter or digit, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: isalpha, Next: isascii, Prev: isalnum, Up: Alphabetical List isalpha ======= Syntax ------ #include <ctype.h> int isalpha(int c); Description ----------- Tells if C is a letter. Return Value ------------ Nonzero if C is a letter, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: isascii, Next: isatty, Prev: isalpha, Up: Alphabetical List isascii ======= Syntax ------ #include <ctype.h> int isascii(int c); Description ----------- Tells if C is an ASCII character (0x00 to 0x7f). Return Value ------------ Nonzero if C is ASCII, else zero. Portability ----------- not ANSI, not POSIX File: libc.info, Node: isatty, Next: iscntrl, Prev: isascii, Up: Alphabetical List isatty ====== Syntax ------ #include <unistd.h> int isatty(int fd); Description ----------- Tells if the file descriptor refers to a terminal device or not. Return Value ------------ Nonzero if FD is a terminal device, zero otherwise. Portability ----------- not ANSI, POSIX Example ------- if (isatty(1)) fflush(stdout); File: libc.info, Node: iscntrl, Next: isdigit, Prev: isatty, Up: Alphabetical List iscntrl ======= Syntax ------ #include <ctype.h> int iscntrl(int c); Description ----------- Tells if C is a control character. Return Value ------------ Nonzero if C is a control character, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: isdigit, Next: isgraph, Prev: iscntrl, Up: Alphabetical List isdigit ======= Syntax ------ #include <ctype.h> int isdigit(int c); Description ----------- Tells if C is a digit. Return Value ------------ Nonzero if C is a digit, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: isgraph, Next: islower, Prev: isdigit, Up: Alphabetical List isgraph ======= Syntax ------ #include <ctype.h> int isgraph(int c); Description ----------- Tells if C is a visible printing character. Space is not included. Return Value ------------ Nonzero if C is a visible printing character, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: islower, Next: isprint, Prev: isgraph, Up: Alphabetical List islower ======= Syntax ------ #include <ctype.h> int islower(int c); Description ----------- Tells if C is lower case or not. Return Value ------------ Nonzero if C is lower case, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: isprint, Next: ispunct, Prev: islower, Up: Alphabetical List isprint ======= Syntax ------ #include <ctype.h> int isprint(int c); Description ----------- Tells if C is a printing character, which includes the space character. Return Value ------------ Nonzero if C is a printing character, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: ispunct, Next: isspace, Prev: isprint, Up: Alphabetical List ispunct ======= Syntax ------ #include <ctype.h> int ispunct(int c); Description ----------- Tells if C is any printing character except space and those indicated by `isalnum'. Return Value ------------ Nonzero if C is punctuation, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: isspace, Next: isupper, Prev: ispunct, Up: Alphabetical List isspace ======= Syntax ------ #include <ctype.h> int isspace(int c); Description ----------- Tells if C is whitespace, that is, carriage return, newline, form feed, tab, vertical tab, or space. Return Value ------------ Nonzero if C is whitespace, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: isupper, Next: isxdigit, Prev: isspace, Up: Alphabetical List isupper ======= Syntax ------ #include <ctype.h> int isupper(int c); Description ----------- Tells if C is an upper case character or not. Return Value ------------ Nonzero if C is upper case, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: isxdigit, Next: itoa, Prev: isupper, Up: Alphabetical List isxdigit ======== Syntax ------ #include <ctype.h> int isxdigit(int c); Description ----------- Tells if C is a valid hexadecimal digit or not. This includes `[0-9a-fA-F]'. Return Value ------------ Nonzero if C is a hex digit, else zero. Portability ----------- ANSI, POSIX File: libc.info, Node: itoa, Next: kbhit, Prev: isxdigit, Up: Alphabetical List itoa ==== Syntax ------ #include <stdlib.h> char * itoa(int value, char *string, int radix) Description ----------- This function converts its argument VALUE into a null-terminated character string using RADIX as the base of the number system. The resulting string with a length of upto 33 bytes (including the optional sign and the terminating `NULL' is put into the buffer whose address is given by STRING. For radixes other than 10, VALUE is treated as an unsigned int (i.e., the sign bit is not interpreted as such). The argument RADIX should specify the base, between 2 and 36, in which the string reprsentation of VALUE is requested. Return Value ------------ A pointer to STRING. Portability ----------- not ANSI, not POSIX Example ------- char binary_str[33]; (void)itoa(num, binary_str, 2); File: libc.info, Node: kbhit, Next: kill, Prev: itoa, Up: Alphabetical List kbhit ===== Syntax ------ #include <pc.h> int kbhit(void); Description ----------- If the user has hit a key, this function will detect it. This function is very fast when there is no key waiting, so it may be used inside loops as needed. If you test shift/alt/ctrl status with bios calls (e.g., using `bioskey (2)' or `bioskey (0x12)') then you should also use bios calls for testing for keys. This can be done with by `bioskey (1)' or `bioskey (0x11)'. Failing to do so can cause trouble in multitasking environments like DESQview/X. Return Value ------------ Nonzero if a key has been hit, else zero. Portability ----------- not ANSI, not POSIX Example ------- while (!kbhit()) do_stuff(); File: libc.info, Node: kill, Next: labs, Prev: kbhit, Up: Alphabetical List kill ==== Syntax ------ #include <signal.h> int kill(pid_t _pid, int _sig); Description ----------- If _PID is the current `getpid()', the given _SIG is raised with *Note raise::. Return Value ------------ -1 on error, else zero. Portability ----------- not ANSI, POSIX File: libc.info, Node: labs, Next: ldexp, Prev: kill, Up: Alphabetical List labs ==== Syntax ------ #include <stdlib.h> long labs(long x); Description ----------- This function takes the absolute value of X. *Note abs::. Return Value ------------ |X| Portability ----------- ANSI, POSIX File: libc.info, Node: ldexp, Next: ldiv, Prev: labs, Up: Alphabetical List ldexp ===== Syntax ------ #include <math.h> double ldexp(double val, int exp); Description ----------- This function computes VAL*2^EXP. Return Value ------------ VAL*2^EXP. `ldexp(0., exp)' returns 0 for all values of `exp', without setting `errno'. For non-zero values of VAL, `errno' is set to `ERANGE' if the result cannot be accurately represented by a `double', and the return value is then the nearest representable `double' (possibly, an `Inf'). If VAL is a `NaN' or `Inf', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX Example ------- ldexp(3.5,4) == 3.5 * (2^4) == 56.0 File: libc.info, Node: ldiv, Next: _lfn_gen_short_fname, Prev: ldexp, Up: Alphabetical List ldiv ==== Syntax ------ #include <stdlib.h> ldiv_t ldiv(long numerator, long denominator); Description ----------- Returns the quotient and remainder of the division NUMERATOR divided by DENOMINATOR. The return type is as follows: typedef struct { long quot; long rem; } ldiv_t; Return Value ------------ The results of the division are returned. Portability ----------- ANSI, POSIX Example ------- ldiv_t l = ldiv(42, 3); printf("42 = %ld x 3 + %ld\n", l.quot, l.rem); ldiv(+40, +3) = { +13, +1 } ldiv(+40, -3) = { -13, -1 } ldiv(-40, +3) = { -13, -1 } ldiv(-40, -3) = { +13, -1 } File: libc.info, Node: _lfn_gen_short_fname, Next: _lfn_get_ftime, Prev: ldiv, Up: Alphabetical List _lfn_gen_short_fname ==================== Syntax ------ #include <fcntl.h> char * _lfn_gen_short_fname (const char *long_fname, char *short_fname); Description ----------- This function generates a short (8+3) filename alias for the long filename pointed to by LONG_FNAME and puts it into the buffer pointed to by SHORT_FNAME. It uses the same algorithm that Windows 9x uses, with the exception that the returned short name will never have a numeric tail, because this function doesn't check the directory to see whether the generated short name will collide with any other file in the directory. Note that LONG_FNAME must contain only the name part of a file; elements of a full pathname (like `:' or `/' are not allowed (they will cause the function to fail). SHORT_FNAME will be returned upper-cased, since that is how 8+3 filenames are stored in directory entries. When the LFN API is not supported (*note _use_lfn::.), the function simply converts up to 12 characters of LONG_FNAME to upper-case and returns that. It will do the same if LONG_FNAME includes any characters illegal in a filename. You might need to call this function if you want to know whether a given filename is valid on MSDOS: if a case-sensitive string comparison function such as `strcmp' (*note strcmp::.) returns a 0 when it compares the original long filename with the short one returned by `_lfn_gen_short_fname', then the filename is a valid DOS name. (Note that if LONG_FNAME is in lower case, it might not compare equal with SHORT_FNAME because of the case difference.) Return value ------------ The function returns a pointer to SHORT_FNAME. Portability ----------- not ANSI, not POSIX Example ------- #include <stdio.h> #include <string.h> #include <fcntl.h> int dos_check (char *fname) { char fshort[13]; int retval; if (stricmp (_lfn_gen_short_fname (fname, fshort), fname) == 0) { printf ("%s is a valid MSDOS 8+3 filename\n", fname); retval = 1; } else { printf ("%s will have to be changed for MSDOS\n", fname); retval = 0; } return retval; } File: libc.info, Node: _lfn_get_ftime, Next: __libc_termios_init, Prev: _lfn_gen_short_fname, Up: Alphabetical List _lfn_get_ftime ============== Syntax ------ #include <fcntl.h> char _lfn_get_ftime (int fhandle, int flag); Description ----------- This function returns creation and access time for files that reside on a filesystem which supports long filenames (such as Windows 95). Files which reside on native FAT filesystems will cause this function to fail. The FHANDLE parameter is the file handle as returned by one of the functions which open or create files. The FLAG parameter determines which time (creation or access) is returned. It can be set to one of the following: `_LFN_ATIME' Causes `_lfn_get_ftime' to return the time when the file was last accessed. (Currently, it actually only returns the *date* of last access; the time bits are all zeroed.) `_LFN_CTIME' Causes `_lfn_get_ftime' to return the time when the file was created. Note that if the file was created by a program which doesn't support long filenames, this time will be zero. Return value ------------ The file time stamp, as a packed unsigned int value: `Bits 0-4' seconds divided by 2 `Bits 5-10' minutes (0-59) `Bits 11-15' hours (0-23) `Bits 16-20' day of the month (1-31) `Bits 21-24' month (1 = January) `Bits 25-31' year offset from 1980 (add 1980 to get the actual year) If the underlying system calls fail, the function will return 0 and set `errno' to an appropriate value. Portability ----------- not ANSI, not POSIX Example ------- unsigned file_stamp = _lfn_get_ftime (handle, _LFN_CTIME); File: libc.info, Node: __libc_termios_init, Next: libm, Prev: _lfn_get_ftime, Up: Alphabetical List __libc_termios_init =================== Syntax ------ #include <libc/ttyprvt.h> void __libc_termios_init (void); Description ----------- This function sets read/write hooks for the termios emulation and import parameters. Currently importing parameters is not supported, the emulation is resolved by only internal(static) parameters. Note that this function is called by tcXXX function automatically. Portability ----------- not ANSI, not POSIX File: libc.info, Node: libm, Next: link, Prev: __libc_termios_init, Up: Alphabetical List libm ==== Syntax ------ #include <libm/math.h> enum fdversion {fdlibm_ieee = -1, fdlibm_svid, fdlibm_xopen, fdlibm_posix}; #define _LIB_VERSION_TYPE enum fdversion #define _LIB_VERSION _fdlib_version extern _LIB_VERSION_TYPE _LIB_VERSION; #define _IEEE_ fdlibm_ieee #define _SVID_ fdlibm_svid #define _XOPEN_ fdlibm_xopen #define _POSIX_ fdlibm_posix _LIB_VERSION_TYPE _LIB_VERSION = _IEEE_; Description ----------- The alternate math library, `libm.a', originally written by "Cygnus support", provides versions of mathematical functions which comply to several different standards of behavior in abnormal cases, and are sometimes more accurate than those included in the default `libc.a' library, in particular when elaborate argument reduction is required to avoid precision loss. Functions in `libm.a' allow to create programs with well-defined and standard-compliant behavior when numerical errors occur, and provide the application with a means to control their behavior in abnormal cases via the `matherr' callback. They almost never rely on the features specific to the x87 FPU, and are thus slower and sometimes slightly less accurate than the functions from `libc.a'. In contrast, the functions in the default `libc.a' library are written for maximum speed and exploitation of the x87 FPU features, do not call `matherr', and are therefore much faster and sometimes more accurate (due to the extended 80-bit precision with which the x87 FPU carries its calculations). Another aspect of differences between functions in `libc.a' and in `libm.a' is the value returned when the result overflows a `double'. The functions from `libc.a' always return a suitably signed infinity, `Inf', whereas for functions from `libm.a' an application can arrange for a large but finite value to be returned. Getting finite return values might be important in certain kinds of mathematical computations where the special rules defined for infinities (e.g., Inf + a = Inf) might be inappropriate. Refer to *Note description of the `libm.a' functions: (libm)Math, for detailed documentation of the individual functions from `libm.a'. This section explains the general setup of using those functions from DJGPP programs. To use the alternate math library with your program, you need to do the following: * Include the header `<libm/math.h>'. Alternatively, you can include `<math.h>' as usual and compile with `-D_USE_LIBM_MATH_H' option to `gcc', which will cause it to use `libm/math.h' instead of the default `math.h'. (The second possibility leaves the source ANSI-compliant.) * Set the global variable `_fdlib_version' to a value other than the default `_IEEE_'. The possible values are listed and explained below. * At the beginning of your `main' function, set the FPU to a predictable state by calling `_clear87' (*note _clear87::.) and `_fpreset' (*note _fpreset::.) library functions. (Another possibility is to make these calls in a function declared with `__attribute__((constructor))', so it will be called before `main'.) * Link your program with the `libm.a' library, e.g. by specifying `-lm' on the link command line. The functions in `libm.a' can emulate different standards. You can select to which standard your program will comply by setting the global variable `_fdlib_version' (or the macro `_LIB_VERSION' which evaluates to it) to one of the values below. This will only affect the behavior of the math functions when an error is signaled by the FPU. `_IEEE_' The default value, specifies IEEE-compliant operation. In case of an error, this version will immediately return whatever result is computed by the FPU, and will *not* set `errno'. If the result overflows, an `Inf' is returned. This version gives the fastest code. `_POSIX_' In case of an error, this version will set `errno' to the appropriate value (`EDOM' or `ERANGE') and return to the caller, without calling the `matherr' function (*note matherr::.). If the result overflows, an `Inf' is returned. This version should be used for maximum POSIX- and ANSI-compliance. `_SVID_' This version is compliant with the "System V Interface Definition". This is the slowest version. In case of an error, it calls the `matherr' function (*note matherr::.), which can be customized to the specific application needs. If `matherr' returns zero, a message is printed to the standard error stream which states the name of the function that generated the error and the error type, and `errno' is set. If `matherr' returns non-zero, there will be no message and `errno' will be left unaltered. If the result overflows, this version returns `HUGE', a large but finite value defined by `libm/math.h'. `_XOPEN_' Complies to the X/Open specifications. It behaves exactly like `_SVID_', but it never prints an error message, even if `matherr' returns zero, and `Inf' us returned when a result overflows. Portability ----------- not ANSI, not POSIX Example ------- /* Testing errno == EDOM after sqrt(-1). !!! MUST compile with -lm !!! */ #include <assert.h> #include <errno.h> #include <stdio.h> #include <libm/math.h> /* or #define _USE_LIBM_MATH_H and #include <math.h> */ #include <float.h> /* Setting _LIB_VERSION to anything but _IEEE_ will turn on errno handling. */ _LIB_VERSION_TYPE _LIB_VERSION = _POSIX_; int main (void) { /* Reset the FPU (possible previous FP problems). */ _clear87 (); _fpreset (); /* Run the test. */ errno = 0; assert(errno == 0); sqrt(-1.0); assert(errno == EDOM); /* this line should NOT cause the assertion to fail */ return(0); } File: libc.info, Node: link, Next: llabs, Prev: libm, Up: Alphabetical List link ==== Syntax ------ #include <unistd.h> int link(const char *exists, const char *new); Description ----------- Because of limitations of MS-DOS, this function doesn't really link two files together. However, it simulates a real `link' by copying the file at EXISTS to NEW. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX Example ------- link("foo.c", "foo.bak"); File: libc.info, Node: llabs, Next: lldiv, Prev: link, Up: Alphabetical List llabs ===== Syntax ------ #include <stdlib.h> long long llabs(long long x); Description ----------- This function takes the absolute value of X. *Note abs::. Return Value ------------ |X| Portability ----------- not ANSI, not POSIX File: libc.info, Node: lldiv, Next: load_npx, Prev: llabs, Up: Alphabetical List lldiv ===== Syntax ------ #include <stdlib.h> lldiv_t lldiv(long long numerator, long long denominator); Description ----------- Returns the quotient and remainder of the division NUMERATOR divided by DENOMINATOR. The return type is as follows: typedef struct { long long quot; long long rem; } lldiv_t; Return Value ------------ The results of the division are returned. Portability ----------- not ANSI, not POSIX Example ------- lldiv_t l = lldiv(42, 3); printf("42 = %lld x 3 + %lld\n", l.quot, l.rem); lldiv(+40, +3) = { +13, +1 } lldiv(+40, -3) = { -13, -1 } lldiv(-40, +3) = { -13, -1 } lldiv(-40, -3) = { +13, -1 } File: libc.info, Node: load_npx, Next: localeconv, Prev: lldiv, Up: Alphabetical List load_npx ======== Syntax ------ #include <debug/dbgcom.h> extern NPX npx; void load_npx (void); Description ----------- This function restores the state of the x87 numeric processor from the data saved in the external variable `npx'. This variable is a structure defined as follows in the header `debug/dbgcom.h': typedef struct { unsigned short sig0; unsigned short sig1; unsigned short sig2; unsigned short sig3; unsigned short exponent:15; unsigned short sign:1; } NPXREG; typedef struct { unsigned long control; unsigned long status; unsigned long tag; unsigned long eip; unsigned long cs; unsigned long dataptr; unsigned long datasel; NPXREG reg[8]; long double st[8]; char st_valid[8]; long double mmx[8]; char in_mmx_mode; char top; } NPX; `load_npx' should be called immediately after `run_child' (*note run_child::.) is called to begin or resume the debugged program, and provided that a call to `save_npx' was issued before `run_child' was called. *Note save_npx::. Portability ----------- not ANSI, not POSIX Example ------- save_npx (); run_child (); load_npx (); File: libc.info, Node: localeconv, Next: localtime, Prev: load_npx, Up: Alphabetical List localeconv ========== Syntax ------ #include <locale.h> struct lconv *localeconv(void); Description ----------- This function returns a pointer to a static structure that contains information about the current locale. The structure contains these fields: `char *currency_symbol' A string that should be used when printing local currency. `char *decimal_point' A string that is used to separate the integer and fractional portions of real numbers in `printf'. Currently, only the first character is significant. `char *grouping' An array of numbers indicating the size of groupings for non-monetary values to the left of the decimal point. The first number is the size of the grouping just before the decimal point. A number of zero means to repeat the previous number indefinitely. A number of `CHAR_MAX' means to group the remainder of the digits together. `char *int_curr_symbol' A string that should be used when formatting monetary values for local currency when the result will be used internationally. `char *mon_decimal_point' A string that separates the interger and fractional parts of monetary values. `char *mon_grouping' Same as grouping, but for monetary values. `char *negative_sign' A string that is used to represent negative monetary values. `char *positive_sign' A string that is used to represent positive monetary values. `char *thousands_sep' The grouping separator for non-monetary values. `char frac_digits' The number of digits to the right of the decimal point for monetary values. `char int_frac_digits' Like frac_digits, but when formatting for international use. `char n_cs_precedes' If nonzero, the currency string should precede the monetary value if the monetary value is negative. `char n_sep_by_space' If nonzero, the currency string and the monetary value should be separated by a space if the monetary value is negative. `char n_sign_posn' Determines the placement of the negative indication string if the monetary value is negative. 0 ($value), (value$) 1 -$value, -value$ 2 $value-, value$- 3 -$value, value-$ 4 $-value, value$- `char p_cs_precedes' `char p_sep_by_space' `char p_sign_posn' These are the same as n_*, but for when the monetary value is positive. Note that any numeric field may have a value of `CHAR_MAX', which indicates that no information is available. Return Value ------------ A pointer to the `struct lconv' structure. Portability ----------- ANSI, POSIX Example ------- struct lconv *l = localeconv; printf("%s%d\n", l->negative_sign, value); File: libc.info, Node: localtime, Next: lock, Prev: localeconv, Up: Alphabetical List localtime ========= Syntax ------ #include <time.h> struct tm *localtime(const time_t *tod); Description ----------- Converts the time represented by TOD into a structure, correcting for the local timezone. See *Note gmtime::, for the description of `struct tm'. Return Value ------------ A pointer to a static structure which is overwritten with each call. Portability ----------- ANSI, POSIX File: libc.info, Node: lock, Next: log, Prev: localtime, Up: Alphabetical List lock ==== Syntax ------ #include <io.h> int lock(int fd, long offset, long length); Description ----------- Locks a region in file FD using MS-DOS file sharing interface. The region of LENGTH bytes, starting from OFFSET, will become entirely inaccessible to other processes. If multiple locks are used on a single file they must be non-overlapping. The lock must be removed before the file is closed. This function will fail unless SHARE, or a network software providing similar interface, is installed. This function is compatible with Borland C++ function of the same name. *Note unlock::. Return Value ------------ Zero if successful, nonzero if not. Portability ----------- not ANSI, not POSIX File: libc.info, Node: log, Next: log10, Prev: lock, Up: Alphabetical List log === Syntax ------ #include <math.h> double log(double x); Description ----------- This function computes the natural logarithm of X. Return Value ------------ The natural logarithm of X. If X is zero, a negative infinity is returned and `errno' is set to `ERANGE'. If X is negative or `+Inf' or a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: log10, Next: log1p, Prev: log, Up: Alphabetical List log10 ===== Syntax ------ #include <math.h> double log10(double x); Description ----------- This function computes the base-10 logarithm of X. Return Value ------------ The logarithm base 10 of X. If X is zero, a negative infinity is returned and `errno' is set to `ERANGE'. If X is negative or `+Inf' or a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: log1p, Next: log2, Prev: log10, Up: Alphabetical List log1p ===== Syntax ------ #include <math.h> double log1p(double x); Description ----------- This function computes the natural logarithm of 1 + X. It is more accurate than `log(1 + X)' for small values of X. Return Value ------------ The natural logarithm of 1 + X. If X is -1, a negative infinity is returned and `errno' is set to `ERANGE'. If X is less than -1 or `+Inf' or a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: log2, Next: longjmp, Prev: log1p, Up: Alphabetical List log2 ==== Syntax ------ #include <math.h> double log2(double x); Description ----------- This function computes the base-2 logarithm of X. Return Value ------------ The base-2 logarithm of X. If X is zero, a negative infinity is returned and `errno' is set to `ERANGE'. If X is negative or `+Inf' or a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: longjmp, Next: lowvideo, Prev: log2, Up: Alphabetical List longjmp ======= Syntax ------ #include <setjmp.h> void longjmp(jmp_buf env, int val); Description ----------- This function reverts back to a CPU state that was stored in ENV by `setjmp' (*note setjmp::.). The state includes all CPU registers, so any variable in a register when `setjmp' was called will be preserved, and all else will be indeterminate. The value passed as VAL will be the return value of `setjmp' when it resumes processing there. If VAL is zero, the return value will be one. Return Value ------------ This function does not return. Portability ----------- ANSI, POSIX Example ------- jmp_buf j; if (setjmp(j)) return; do_something(); longjmp(j, 1); File: libc.info, Node: lowvideo, Next: lseek, Prev: longjmp, Up: Alphabetical List lowvideo ======== Syntax ------ #include <conio.h> void lowvideo(void); Description ----------- Causes any new characters put on the screen to be dim. Portability ----------- not ANSI, not POSIX File: libc.info, Node: lseek, Next: malloc, Prev: lowvideo, Up: Alphabetical List lseek ===== Syntax ------ #include <unistd.h> off_t lseek(int fd, off_t offset, int whence); Description ----------- This function moves the file pointer for handle FD according to WHENCE: `SEEK_SET' The file pointer is moved to the OFFSET specified. `SEEK_CUR' The file pointer is moved OFFSET bytes relative to its current position. `SEEK_END' The file pointer is moved to a position OFFSET bytes from the end of the file. The value of OFFSET is usually nonpositive in this case. Return Value ------------ The new offset is returned. Portability ----------- not ANSI, POSIX Example ------- lseek(fd, 12, SEEK_CUR); /* skip 12 bytes */ File: libc.info, Node: malloc, Next: matherr, Prev: lseek, Up: Alphabetical List malloc ====== Syntax ------ #include <stdlib.h> void *malloc(size_t size); Description ----------- This function allocates a chunk of memory from the heap large enough to hold any object that is SIZE bytes in length. This memory must be returned to the heap with `free' (*note free::.). Note: this version of malloc is designed to reduce memory usage. A faster but less efficient version is available in the libc sources (djlsr*.zip) in src/libc/ansi/stdlib/fmalloc.c Return Value ------------ A pointer to the allocated memory, or `NULL' if there isn't enough free memory to satisfy the request. Portability ----------- ANSI, POSIX Example ------- char *c = (char *)malloc(100); File: libc.info, Node: matherr, Next: mblen, Prev: malloc, Up: Alphabetical List matherr ======= Syntax ------ #include <libm/math.h> enum fdversion _fdlib_version = _SVID_; int matherr(struct exception *exc); Description ----------- `matherr' is a user-definable handler for errors in math library functions. It is only supported in the alternate math library (link with `-lm'), and will only be called if the global variable `_fdlib_version' is set to either `_SVID_' or `_XOPEN_' (*note libm::.). You also need to mask the Invalid Operation exception in the x87 control word (*note _control87::.) or install a handler for signal `SIGFPE' (*note signal::.), or else some exceptions will generate `SIGFPE' and your program will be terminated before it gets a chance to call `matherr'. DJGPP versions 2.02 and later mask all FP exceptions at startup, so this consideration applies only to programs that unmask FP exceptions at run time. If the above conditions are met, every math function will call `matherr' when a numerical exception is detected. The default version of `matherr', supplied with `libm.a', does nothing and returns zero (the `_SVID_' version will then print an error message to the standard error stream and set `errno'). This default behavior is inappropriate in some cases. For example, an interactive program which runs in a windowed environment might want the error message to go to a particular window, or pop up a dialog box; a fault-tolerant program might want to fall back to backup procedures so that meaningful results are returned to the application code, etc. In such cases, you should include your own version of `matherr' in your program. `matherr' is called with a single argument EXC which is a pointer to a structure defined on `<libm/math.h>' like this: struct exception { int type; char *name; double arg1, arg2, retval; }; The member `type' is an integer code describing the type of exception that has occured. It can be one of the following: `DOMAIN' Argument(s) are outside the valid function domain (e.g., `log(-1)'). `SING' Argument(s) would result in a singularity (e.g., `log(0)'). `OVERFLOW' The result causes overflow, like in `exp(10000)'. `UNDERFLOW' The result causes underflow, like in `exp(-10000)'. `TLOSS' The result loses all significant digits, like in `sin(10e100)'. These codes are defined on `<libm/math.h>'. The member `name' points to the string that is the name of the function which generated the exception. The members `arg1' and `arg2' are the values of the arguments with which the function was called (`arg2' is undefined if the function only accepts a single argument). The member `retval' is set to the default value that will be returned by the math library function; `matherr' can change it to return a different value. Return Value ------------ `matherr' should return zero if it couldn't handle the exception, or non-zero if the exception was handled. If `matherr' returns zero, under `_SVID_' version an error message is printed which includes the name of the function and the exception type, and under `_SVID_' and `_XOPEN_' `errno' is set to an appropriate value. If `matherr' returns non-zero, no error message is printed and `errno' is left unchanged. Portability ----------- not ANSI, not POSIX Example ------- #include <libm/math.h> int matherr(register struct exception *x) { switch (x->type) { case DOMAIN: /* change sqrt to return sqrt(-arg1), not NaN */ if (!strcmp(x->name, "sqrt")) { x->retval = sqrt(-x->arg1); return 1; /* be silent: no message, don't set errno */ } /* FALL THROUGH */ case SING: /* all other domain or sing exceptions, print message and abort */ fprintf(stderr, "domain exception in %s\n", x->name); abort(); break; } return 0; /* all other exceptions, execute default procedure */ } File: libc.info, Node: mblen, Next: mbstowcs, Prev: matherr, Up: Alphabetical List mblen ===== Syntax ------ #include <stdlib.h> int mblen(const char *s, size_t n); Description ----------- This function returns the number of characters of string S that make up the next multibyte character. No more than N characters are checked. If S is `NULL', the internal shift state is reset. Return Value ------------ The number of characters that comprise the next multibyte character. Portability ----------- ANSI, POSIX Example ------- int n = mblen(string, INT_MAX); string += n; File: libc.info, Node: mbstowcs, Next: mbtowc, Prev: mblen, Up: Alphabetical List mbstowcs ======== Syntax ------ #include <stdlib.h> size_t mbstowcs(wchar_t *wcs, const char *s, size_t n); Description ----------- Converts a multibyte string to a wide character string. The result will be no more than N wide characters. Return Value ------------ The number of wide characters stored. Portability ----------- ANSI, POSIX Example ------- int wlen = mbtowcs(wbuf, string, sizeof(wbuf)/sizeof(wchar_t)); File: libc.info, Node: mbtowc, Next: memccpy, Prev: mbstowcs, Up: Alphabetical List mbtowc ====== Syntax ------ #include <stdlib.h> int mbtowc(wchar_t *pwc, const char *s, size_t n); Description ----------- Convert the first multibyte sequence in S to a wide character. At most N characters are checked. If PWC is not `NULL', the result is stored there. If S is null, the internal shift state is reset. Return Value ------------ The number of characters used by the multibyte sequence. Portability ----------- ANSI, POSIX Example ------- string += mbtowc(&wc, string, strlen(string)); File: libc.info, Node: memccpy, Next: memchr, Prev: mbtowc, Up: Alphabetical List memccpy ======= Syntax ------ #include <string.h> void * memccpy(void *to, const void *from, int ch, size_t nbytes) Description ----------- This function copies characters from memory area FROM into TO, stopping after the first occurrence of character CH has been copied, or after NBYTES characters have been copied, whichever comes first. The buffers should not overlap. Return Value ------------ A pointer to the character after the copy of CH in TO, or a `NULL' pointer if CH was not found in the first NBYTES characters of FROM. Portability ----------- not ANSI, not POSIX Example ------- char inpbuf[256], dest[81]; printf("Enter a path: "); fflush(stdout); gets(inpbuf); memset(dest, 0, sizeof(dest)); if (memccpy(dest, inpbuf, '\\', 80)) printf("The first directory in path is %s\n", dest); else printf("No explicit directory in path\n"); File: libc.info, Node: memchr, Next: memcmp, Prev: memccpy, Up: Alphabetical List memchr ====== Syntax ------ #include <string.h> void *memchr(const void *string, int ch, size_t num); Description ----------- This function searches NUM bytes starting at STRING, looking for the first occurence of CH. Return Value ------------ A pointer to the first match, or `NULL' if it wasn't found. Portability ----------- ANSI, POSIX Example ------- if (memchr(path, '/', strlen(path)) do_slash(); File: libc.info, Node: memcmp, Next: memcpy, Prev: memchr, Up: Alphabetical List memcmp ====== Syntax ------ #include <string.h> int memcmp(const void *s1, const void *s2, size_t num); Description ----------- This function compares two regions of memory, at S1 and S2, for NUM bytes. Return Value ------------ zero s1 == s2 positive s1 > s2 negative s1 < s2 Portability ----------- ANSI, POSIX File: libc.info, Node: memcpy, Next: memicmp, Prev: memcmp, Up: Alphabetical List memcpy ====== Syntax ------ #include <string.h> void *memcpy(void *dest, const void *src, int num); Description ----------- This function copies NUM bytes from SOURCE to DEST. It assumes that the source and destination regions don't overlap; if you need to copy overlapping regions, use `memmove' instead. *Note memmove::. Return Value ------------ DEST Portability ----------- ANSI, POSIX Example ------- memcpy(buffer, temp_buffer, BUF_MAX); File: libc.info, Node: memicmp, Next: memmove, Prev: memcpy, Up: Alphabetical List memicmp ======= Syntax ------ #include <string.h> int memicmp(const void *s1, const void *s2, size_t num); Description ----------- This function compares two regions of memory, at S1 and S2, for NUM bytes, disregarding case. Return Value ------------ Zero if they're the same, nonzero if different, the sign indicates "order". Portability ----------- not ANSI, not POSIX Example ------- if (memicmp(arg, "-i", 2) == 0) /* '-I' or '-include' etc. */ do_include(); File: libc.info, Node: memmove, Next: memset, Prev: memicmp, Up: Alphabetical List memmove ======= Syntax ------ #include <string.h> void *memmove(void *dest, const void *source, int num); Description ----------- This function copies NUM bytes from SOURCE to DEST. The copy is done in such a way that if the two regions overlap, the source is always read before that byte is changed by writing to the destination. Return Value ------------ DEST Portability ----------- ANSI, POSIX Example ------- memmove(buf+1, buf, 99); memmove(buf, buf+1, 99); File: libc.info, Node: memset, Next: mkdir, Prev: memmove, Up: Alphabetical List memset ====== Syntax ------ #include <string.h> void *memset(void *buffer, int ch, size_t num); Description ----------- This function stores NUM copies of CH, starting at BUFFER. This is often used to initialize objects to a known value, like zero. Note that, although CH is declared `int' in the prototype, `memset' only uses its least-significant byte to fill BUFFER. Return Value ------------ BUFFER Portability ----------- ANSI, POSIX Example ------- struct tm t; memset(&t, 0, sizeof(t)); File: libc.info, Node: mkdir, Next: mkfifo, Prev: memset, Up: Alphabetical List mkdir ===== Syntax ------ #include <sys/stat.h> int mkdir(const char *path, mode_t mode); Description ----------- This function creates a subdirectory. All the bits except `S_IWUSR' in the MODE argument are ignored under MS-DOS. If `S_IWUSR' is *not* set in MODE, the directory is created with read-only attribute bit set. Note that DOS itself ignores the read-only bit of directories, but some programs do not. Return Value ------------ Zero if the subdirectory was created, nonzero on failure. Portability ----------- not ANSI, POSIX Example ------- mkdir("/usr/tmp", S_IWUSR); File: libc.info, Node: mkfifo, Next: mknod, Prev: mkdir, Up: Alphabetical List mkfifo ====== Syntax ------ #include <sys/stat.h> int mkfifo(const char *path, mode_t mode); Description ----------- This function is provided only to assist in porting from Unix. It always returns an error condition. Portability ----------- not ANSI, POSIX File: libc.info, Node: mknod, Next: mkstemp, Prev: mkfifo, Up: Alphabetical List mknod ===== Syntax ------ #include <sys/stat.h> int mknod(const char *path, mode_t mode, dev_t dev); Description ----------- This function is provided to assist in porting from Unix. If MODE specifies a regular file, `mknod' creates a file using PATH as its name. If MODE specifies a character device, and if the device whose name is given by PATH exists and its device specification as returned by `stat' or `fstat' is equal to DEV, `mknod' returns -1 and sets `errno' to `EEXIST'. In all other cases, -1 is returned `errno' is set to `EACCES'. The argument DEV is ignored if MODE does not specify a character device. Return Value ------------ Zero on success, -1 on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: mkstemp, Next: mktemp, Prev: mknod, Up: Alphabetical List mkstemp ======= Syntax ------ #include <stdio.h> int mkstemp(char *template); Description ----------- TEMPLATE is a file specification that ends with six trailing `X' characters. This function replaces the `XXXXXX' with a set of characters such that the resulting file name names a nonexisting file. It then creates and opens the file in a way which guarantees that no other process can access this file. Note that since MS-DOS is limited to eight characters for the file name, and since none of the `X''s get replaced by a dot, you can only have two additional characters before the `X''s. Note also that the path you give will be modified in place. Return Value ------------ The open file descriptor. Portability ----------- not ANSI, not POSIX Example ------- char path[100]; strcpy(path, "/tmp/ccXXXXXX"); int fd = mkstemp(path); File: libc.info, Node: mktemp, Next: mktime, Prev: mkstemp, Up: Alphabetical List mktemp ====== Syntax ------ #include <stdio.h> char *mktemp(char *template); Description ----------- TEMPLATE is a file specification that ends with six trailing `X' characters. This function replaces the `XXXXXX' with a set of characters such that the resulting file name names a nonexisting file. Note that since MS-DOS is limited to eight characters for the file name, and since none of the `X''s get replaced by a dot, you can only have two additional characters before the `X''s. Return Value ------------ The resulting filename. Portability ----------- not ANSI, not POSIX Example ------- char template[] = "/tmp/ccXXXXXX"; mktemp(template); FILE *q = fopen(template, "w"); File: libc.info, Node: mktime, Next: modf, Prev: mktemp, Up: Alphabetical List mktime ====== Syntax ------ #include <time.h> time_t mktime(struct tm *tptr); Description ----------- This function converts a time structure into the number of seconds since 00:00:00 GMT 1/1/1970. It also attempts to normalize the fields of TPTR. The layout of a `struct tm' is as follows: struct tm { int tm_sec; /* seconds after the minute [0-60] */ int tm_min; /* minutes after the hour [0-59] */ int tm_hour; /* hours since midnight [0-23] */ int tm_mday; /* day of the month [1-31] */ int tm_mon; /* months since January [0-11] */ int tm_year; /* years since 1900 */ int tm_wday; /* days since Sunday [0-6] */ int tm_yday; /* days since January 1 [0-365] */ int tm_isdst; /* Daylight Savings Time flag */ long tm_gmtoff; /* offset from GMT in seconds */ char * tm_zone; /* timezone abbreviation */ }; If you don't know whether daylight saving is in effect at the moment specified by the contents of TPTR, set the `tm_isdst' member to -1, which will cause `mktime' to compute the DST flag using the data base in the `zoneinfo' subdirectory of your main DJGPP installation. This requires that you set the environment variable `TZ' to a file in that directory which corresponds to your geographical area. Return Value ------------ The resulting time, or -1 if the time in TPTR cannot be described in that format. Portability ----------- ANSI, POSIX File: libc.info, Node: modf, Next: modfl, Prev: mktime, Up: Alphabetical List modf ==== Syntax ------ #include <math.h> double modf(double x, double *pint); Description ----------- `modf' breaks down X into its integer portion (which it stores in *PINT) and the remaining fractional portion, which it returns. Both integer and fractional portions have the same sign as X, except if X is a negative zero, in which case the integer part is a positive zero. Return Value ------------ The fractional portion. If X is `Inf' or `NaN', the return value is zero, the integer portion stored in *PINT is the same as the value of X, and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: modfl, Next: _mono_clear, Prev: modf, Up: Alphabetical List modfl ===== Syntax ------ #include <math.h> long double modf(long double x, long double *pint); Description ----------- `modfl' breaks down X into its integer portion (which it stores in *PINT) and the remaining fractional portion, which it returns. Return Value ------------ The fractional portion. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _mono_clear, Next: _mono_printf, Prev: modfl, Up: Alphabetical List _mono_clear =========== Syntax ------ #include <sys/mono.h> void _mono_clear(void); Description ----------- Clears the monochrome monitor. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _mono_printf, Next: _mono_putc, Prev: _mono_clear, Up: Alphabetical List _mono_printf ============ Syntax ------ #include <sys/mono.h> void _mono_printf(const char *fmt, ...); Description ----------- Like *Note printf::, but prints to the monochrome monitor. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _mono_putc, Next: movedata, Prev: _mono_printf, Up: Alphabetical List _mono_putc ========== Syntax ------ #include <sys/mono.h> void _mono_putc(int c); Description ----------- Prints a single character to the monochrome monitor. Portability ----------- not ANSI, not POSIX File: libc.info, Node: movedata, Next: movedatab, Prev: _mono_putc, Up: Alphabetical List movedata ======== Syntax ------ #include <sys/movedata.h> void movedata(unsigned source_selector, unsigned source_offset, unsigned dest_selector, unsigned dest_offset, size_t length); Description ----------- This function allows the caller to directly transfer information between conventional and linear memory, and among each as well. The selectors passed are *not* segment values like in DOS. They are protected mode selectors that can be obtained by the `_my_ds' and `_go32_info_block.selector_for_linear_memory' (or just `_dos_ds') functions (*Note _my_ds::, *Note _go32_info_block::). The offsets are linear offsets. If the selector is for the program's data area, this offset corresponds to the address of a buffer (like `(unsigned)&something'). If the selector is for the conventional memory area, the offset is the physical address of the memory, which can be computed from a traditional segment/offset pair as `segment'*16+`offset'. For example, the color text screen buffer is at offset 0xb8000. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- short blank_row_buf[ScreenCols()]; /* scroll screen */ movedata(_dos_ds, 0xb8000 + ScreenCols()*2, _dos_ds, 0xb8000, ScreenCols() * (ScreenRows()-1) * 2); /* fill last row */ movedata(_my_ds(), (unsigned)blank_row_buf, _dos_ds, 0xb8000 + ScreenCols()*(ScreenRows()-1)*2, ScreenCols() * 2); File: libc.info, Node: movedatab, Next: movedatal, Prev: movedata, Up: Alphabetical List movedatab ========= Syntax ------ #include <sys/movedata.h> void _movedatab(unsigned, unsigned, unsigned, unsigned, size_t); Description ----------- Just like *Note movedata::, but all transfers are always 8-bit transfers. Portability ----------- not ANSI, not POSIX File: libc.info, Node: movedatal, Next: movedataw, Prev: movedatab, Up: Alphabetical List movedatal ========= Syntax ------ #include <sys/movedata.h> void _movedatal(unsigned, unsigned, unsigned, unsigned, size_t); Description ----------- Just like *Note movedata::, but all transfers are always 32-bit transfers, and the count is a count of transfers, not bytes. Portability ----------- not ANSI, not POSIX File: libc.info, Node: movedataw, Next: movetext, Prev: movedatal, Up: Alphabetical List movedataw ========= Syntax ------ #include <sys/movedata.h> void _movedataw(unsigned, unsigned, unsigned, unsigned, size_t); Description ----------- Just like *Note movedata::, but all transfers are always 16-bit transfers, and the count is a count of transfers, not bytes. Portability ----------- not ANSI, not POSIX File: libc.info, Node: movetext, Next: mprotect, Prev: movedataw, Up: Alphabetical List movetext ======== Syntax ------ #include <conio.h> int movetext(int _left, int _top, int _right, int _bottom, int _destleft, int _desttop); Description ----------- Moves a block of text on the screen. Return Value ------------ 1 on success, zero on error. Portability ----------- not ANSI, not POSIX File: libc.info, Node: mprotect, Next: _my_cs, Prev: movetext, Up: Alphabetical List mprotect ======== Syntax ------ #include <sys/types.h> #include <sys/mman.h> int mprotect(void *addr, size_t len, int prot); Description ----------- This function modifies the access protection of a memory region. Protection occurs in 4Kbyte regions (pages) aligned on 4Kbyte boundaries. All pages in the region will be changed, so ADDR and LEN should be multiples of 4096. The protection PROT for each page is specified with the values: PROT_NONE Region can not be touched (if or'ed is ignored). PROT_READ Region can be read (can be or'ed with PROT_WRITE). PROT_WRITE Region can be written (implies read access). This function is only supported on DPMI hosts which provide some V1.0 extensions on V0.9 memory blocks. Return Value ------------ The function returns 0 if successful and the value -1 if all the pages could not be set. Portability ----------- not ANSI, not POSIX Example ------- mprotect(readonly_buffer,8192,PROT_READ); mprotect(guard_area,4096,PROT_NONE); mprotect(NULL,4096,PROT_WRITE); /* Let NULL pointers not generate exceptions */ File: libc.info, Node: _my_cs, Next: _my_ds, Prev: mprotect, Up: Alphabetical List _my_cs ====== Syntax ------ #include <sys/segments.h> unsigned short _my_cs(); Description ----------- Returns the current `CS'. This is useful for setting up interrupt vectors and such. Return Value ------------ `CS' Portability ----------- not ANSI, not POSIX File: libc.info, Node: _my_ds, Next: _my_ss, Prev: _my_cs, Up: Alphabetical List _my_ds ====== Syntax ------ #include <sys/segments.h> unsigned short _my_ds(); Description ----------- Returns the current `DS'. This is useful for setting up interrupt vectors and such. Return Value ------------ `DS' Portability ----------- not ANSI, not POSIX File: libc.info, Node: _my_ss, Next: nice, Prev: _my_ds, Up: Alphabetical List _my_ss ====== Syntax ------ #include <sys/segments.h> unsigned short _my_ss(); Description ----------- Returns the current `SS'. This is useful for setting up interrupt vectors and such. Return Value ------------ `SS' Portability ----------- not ANSI, not POSIX File: libc.info, Node: nice, Next: normvideo, Prev: _my_ss, Up: Alphabetical List nice ==== Syntax ------ #include <unistd.h> int nice(int _increment); Description ----------- Adjusts the priority of the process. Provided for Unix compatibility only. Return Value ------------ The new nice value. Portability ----------- not ANSI, not POSIX File: libc.info, Node: normvideo, Next: nosound, Prev: nice, Up: Alphabetical List normvideo ========= Syntax ------ #include <conio.h> void normvideo(void); Description ----------- Resets the text attribute to what it was before the program started. Portability ----------- not ANSI, not POSIX File: libc.info, Node: nosound, Next: ntohl, Prev: normvideo, Up: Alphabetical List nosound ======= Syntax ------ #include <pc.h> void nosound(void); Description ----------- Disable the PC speaker. Portability ----------- not ANSI, not POSIX File: libc.info, Node: ntohl, Next: ntohs, Prev: nosound, Up: Alphabetical List ntohl ===== Syntax ------ #include <netinet/in.h> unsigned long ntohl(unsigned long val); Description ----------- This function converts from network formatted longs to host formatted longs. For the i386 and higher processors, this means that the bytes are swapped from 1234 order to 4321 order. Return Value ------------ The host-order value. Portability ----------- not ANSI, not POSIX Example ------- ip = ntohl(packet.ipaddr); File: libc.info, Node: ntohs, Next: open, Prev: ntohl, Up: Alphabetical List ntohs ===== Syntax ------ #include <netinet/in.h> unsigned short ntohs(unsigned short val); Description ----------- This function converts from network formatted shorts to host formatted shorts. For the i386 and higher processors, this means that the bytes are swapped from 12 order to 21 order. Return Value ------------ The host-order value. Portability ----------- not ANSI, not POSIX Example ------- port = ntohs(tcp.port); File: libc.info, Node: open, Next: _open, Prev: ntohs, Up: Alphabetical List open ==== Syntax ------ #include <fcntl.h> #include <sys/stat.h> /* for mode definitions */ int open(const char *file, int mode /*, int permissions */); Description ----------- This function opens the named FILE in the given MODE, which is any combination of the following: `O_RDONLY' The file is opened for reading. `O_WRONLY' The file is opened for writing. `O_RDWR' The file is opened for both reading and writing. `O_CREAT' If the file does not exist, it is created. *Note creat::. `O_TRUNC' If the file does exist, it is truncated to zero bytes. `O_EXCL' If the file exists, and `O_CREAT' is also specified, the `open' call will fail. `O_APPEND' The file pointer is positioned at the end of the file before each write. `O_TEXT' The file is opened in text mode, meaning that Ctrl-M characters are stripped on reading and added on writing as needed. The default mode is specified by the `_fmode' variable *Note _fmode::. `O_BINARY' The file is opened in binary mode. When called to open the console in binary mode, `open' will disable the generation of `SIGINT' when you press `Ctrl-C' (`Ctrl-Break' will still cause `SIGINT'), because many programs that use binary reads from the console will also want to get the `^C' characters. You can use the `__djgpp_set_ctrl_c' library function (*note __djgpp_set_ctrl_c::.) if you want `Ctrl-C' to generate interrupts while console is read in binary mode. If the file is created by this call, it will be given the read/write permissions specified by PERMISSIONS, which may be any combination of these values: `S_IRUSR' The file is readable. This is always true for MS-DOS. `S_IWUSR' The file is writable. Other `S_I*' values may be included, but they will be ignored. You can specify the share flags (a DOS specific feature) in MODE. And you can indicate default values for the share flags in `__djgpp_share_flags'. *Note __djgpp_share_flags::. Return Value ------------ If successful, the file descriptor is returned. On error, a negative number is returned and `errno' is set to indicate the error. Portability ----------- not ANSI, POSIX Example ------- int q = open("/tmp/foo.dat", O_RDONLY|O_BINARY); File: libc.info, Node: _open, Next: opendir, Prev: open, Up: Alphabetical List _open ===== Syntax ------ #include <io.h> int _open(const char *path, int attrib); Description ----------- This is a direct connection to the MS-DOS open function call, int 0x21, %ah = 0x3d. (When long file names are supported, `_open' calls function 0x716c of Int 0x21.) The file is set to binary mode. This function can be hooked by the "File System Extensions" (*note File System Extensions::.). If you don't want this, you should use `_dos_open' (*note _dos_open::.) (but note that the latter doesn't support long file names). Return Value ------------ The new file descriptor, else -1 on error. Portability ----------- not ANSI, not POSIX File: libc.info, Node: opendir, Next: outb, Prev: _open, Up: Alphabetical List opendir ======= Syntax ------ #include <dirent.h> extern int __opendir_flags; DIR *opendir(char *name); Description ----------- This function "opens" a directory so that you can read the list of file names in it. The pointer returned must be passed to `closedir' when you are done with it. *Note readdir::. The global variable `__opendir_flags' can be set to include the following values to control the operation of `opendir': `__OPENDIR_PRESERVE_CASE' Do not change the case of files to lower case. Just in case Micros*ft decides to support case-sensitive file systems some day. You can also use this flag if you want the names of files like `README' and `FAQ' from Unix distributions to be returned in upper-case on Windows 9X filesystems. *Note _preserve_fncase::, for other ways of achieving this and for more detailed description of the automatic letter-case conversion by DJGPP library functions. `__OPENDIR_NO_HIDDEN' Do not include hidden files and directories in the search. By default, all files and directories are included. `__OPENDIR_FIND_HIDDEN' Provided for back-compatibility with previous DJGPP versions, where hidden files and directories were by default skipped. In versions 2.02 and later, this flag has no effect. `__OPENDIR_FIND_LABEL' Include volume labels in the search. By default, these are skipped. You can simply put `int __opendir_flags = ...;' in your code. The default is to let it get set to zero as an uninitialized variable. Return Value ------------ The open directory structure, or `NULL' on error. Portability ----------- not ANSI, POSIX (see note 1) Notes: 1. The `__opendir_flags' variable is DJGPP-specific. Example ------- DIR *d = opendir("."); closedir(d); File: libc.info, Node: outb, Next: outp, Prev: opendir, Up: Alphabetical List outb ==== Syntax ------ #include <pc.h> void outb(unsigned short _port, unsigned char _data); Description ----------- Calls *Note outportb::. Provided only for compatibility. Portability ----------- not ANSI, not POSIX File: libc.info, Node: outp, Next: outportb, Prev: outb, Up: Alphabetical List outp ==== Syntax ------ #include <pc.h> void outp(unsigned short _port, unsigned char _data); Description ----------- Calls *Note outportb::. Provided only for compatibility. Portability ----------- not ANSI, not POSIX File: libc.info, Node: outportb, Next: outportl, Prev: outp, Up: Alphabetical List outportb ======== Syntax ------ #include <pc.h> void outportb(unsigned short _port, unsigned char _data); Description ----------- Write a single byte to an 8-bit port. This function is provided as an inline assembler macro, and will be optimized down to a single opcode when you optimize your program. Portability ----------- not ANSI, not POSIX File: libc.info, Node: outportl, Next: outportsb, Prev: outportb, Up: Alphabetical List outportl ======== Syntax ------ #include <pc.h> void outportl(unsigned short _port, unsigned long _data); Description ----------- Write a single long to an 32-bit port. This function is provided as an inline assembler macro, and will be optimized down to a single opcode when you optimize your program. Portability ----------- not ANSI, not POSIX File: libc.info, Node: outportsb, Next: outportsl, Prev: outportl, Up: Alphabetical List outportsb ========= Syntax ------ #include <pc.h> void outportsb(unsigned short _port, const unsigned char *_buf, unsigned _len); Description ----------- Writes the _LEN bytes in _BUF to the 8-bit _PORT. Portability ----------- not ANSI, not POSIX File: libc.info, Node: outportsl, Next: outportsw, Prev: outportsb, Up: Alphabetical List outportsl ========= Syntax ------ #include <pc.h> void outportsl(unsigned short _port, const unsigned long *_buf, unsigned _len); Description ----------- Writes the _LEN longs in _BUF to the 32-bit _PORT. Portability ----------- not ANSI, not POSIX File: libc.info, Node: outportsw, Next: outportw, Prev: outportsl, Up: Alphabetical List outportsw ========= Syntax ------ #include <pc.h> void outportsw(unsigned short _port, const unsigned short *_buf, unsigned _len); Description ----------- Writes the _LEN shorts in _BUF to the 16-bit _PORT. Portability ----------- not ANSI, not POSIX File: libc.info, Node: outportw, Next: outpw, Prev: outportsw, Up: Alphabetical List outportw ======== Syntax ------ #include <pc.h> void outportw(unsigned short _port, unsigned short _data); Description ----------- Write a single short to an 16-bit port. This function is provided as an inline assembler macro, and will be optimized down to a single opcode when you optimize your program. Portability ----------- not ANSI, not POSIX File: libc.info, Node: outpw, Next: pathconf, Prev: outportw, Up: Alphabetical List outpw ===== Syntax ------ #include <pc.h> void outpw(unsigned short _port, unsigned short _data); Description ----------- Calls *Note outportw::. Provided only for compatibility. Portability ----------- not ANSI, not POSIX File: libc.info, Node: pathconf, Next: pause, Prev: outpw, Up: Alphabetical List pathconf ======== Syntax ------ #include <unistd.h> long pathconf(const char *filename, int name); Description ----------- This function returns various system-dependent configuration values. The NAME is one of the following: `_PC_LINK_MAX' The maximum number of directory entries that can refer to a single real file. Always 1 in DJGPP. `_PC_MAX_CANON' The maximum number of bytes in an editable input line. In DJGPP, this is 126 (DOS restriction). `_PC_MAX_INPUT' The maximum number of bytes in a non-editable input line. Also 126 in DJGPP. `_PC_NAME_MAX' The maximum length of an individual file name. If the filesystem where FILENAME resides supports long file names, the result is whatever `_get_volume_info' returns (usually 255); otherwise 12 will be returned. *Note _use_lfn::. `_PC_PATH_MAX' The maximum length of a complete path name. If the filesystem where FILENAME resides supports long file names, the result is whatever `_get_volume_info' returns (usually 260); otherwise 80 will be returned. *Note _use_lfn::. `_PC_PIPE_BUF' The size of a pipe's internal buffer. In DJGPP, this returns 512. `_PC_CHOWN_RESTRICTED' If non-zero, only priviledged user can change the ownership of files by calling `chown', otherwise anyone may give away files. The DJGPP version always returns zero, since MS-DOS files can be freely given away. `_PC_NO_TRUNC' If zero is returned, filenames longer than what `pathconf (filename, _PC_NAME_MAX)' returns are truncated, otherwise an error occurs if you use longer names. In DJGPP, this returns 0, since DOS always silently truncates long names. `_PC_VDISABLE' A character to use to disable tty special characters. DJGPP currently doesn't support special characters, so this returns -1. Return Value ------------ The selected configuration value is returned. Portability ----------- not ANSI, POSIX Example ------- char *buf = malloc(pathconf("c:/", _PC_MAX_PATH)+1); File: libc.info, Node: pause, Next: pclose, Prev: pathconf, Up: Alphabetical List pause ===== Syntax ------ #include <unistd.h> int pause(void); Description ----------- This function just calls `__dpmi_yield()' (*note __dpmi_yield::.) to give up a slice of the CPU. Return Value ------------ Zero. Portability ----------- not ANSI, POSIX File: libc.info, Node: pclose, Next: perror, Prev: pause, Up: Alphabetical List pclose ====== Syntax ------ #include <stdio.h> int pclose(FILE *pipe); Description ----------- This function closes a pipe opened with `popen' (*note popen::.). Note that since MS-DOS is not multitasking, this function will actually run the program specified in `popen' if the pipe was opened for writing. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX Example ------- FILE *f = popen("sort", "w"); write_to_pipe(f); pclose(f); File: libc.info, Node: perror, Next: pipe, Prev: pclose, Up: Alphabetical List perror ====== Syntax ------ #include <stdio.h> void perror(const char *string); Description ----------- This function formats an error message and prints it to `stderr'. The message is the STRING, a colon, and a message suitable for the error condition indicated by `errno'. Return Value ------------ None. Portability ----------- ANSI, POSIX Example ------- int x = open("foo", O_RDONLY); if (x < 0) { perror("foo"); exit(1); } File: libc.info, Node: pipe, Next: popen, Prev: perror, Up: Alphabetical List pipe ==== Syntax ------ #include <unistd.h> int pipe(int fildes[2]); Description ----------- This function is provided only to assist in porting from Unix. It always returns an error condition. Portability ----------- not ANSI, POSIX File: libc.info, Node: popen, Next: pow, Prev: pipe, Up: Alphabetical List popen ===== Syntax ------ #include <stdio.h> FILE *popen(const char *program, const char *mode); Description ----------- This function executes the named `program' and attaches either its input stream or its output stream to the returned file. While the file is open, the calling program can write to the program (if the program was open for writing) or read the program's output (if the program was opened for reading). When the program is done, or if you have no more input for it, pass the file pointer to `pclose' (*note pclose::.), which terminates the program. Since MS-DOS does not support multitasking, this function actually runs the entire program when the program is opened for reading, and stores the output in a temporary file. `pclose' then removes that file. Similarly, when you open a program for writing, a temp file holds the data and `pclose' runs the entire program. The MODE is the same as for `fopen' (*note fopen::.). Return Value ------------ An open file which can be used to read the program's output or write to the program's input. Portability ----------- not ANSI, POSIX Example ------- FILE *p = popen("dir", "r"); read_program(p); pclose(p); File: libc.info, Node: pow, Next: pow10, Prev: popen, Up: Alphabetical List pow === Syntax ------ #include <math.h> double pow(double x, double y); Description ----------- This function computes X^Y, X raised to the power Y. Return Value ------------ X raised to the power Y. If the result overflows a `double' or underflows, `errno' is set to `ERANGE'. If Y is `NaN', the return value is `NaN' and `errno' is set to `EDOM'. If X and Y are both 0, the return value is 1, but `errno' is set to `EDOM'. If Y is a positive or a negative Infinity, the following results are returned, depending on the value of X: X negative the return value is `NaN' and `errno' is set to `EDOM'. absolute value of X less than 1 and Y is `+Inf' absolute value of X greater than 1 and Y is `-Inf' the return value is zero. absolute value of X less than 1 and Y is `-Inf' absolute value of X greater than 1 and Y is `+Inf' the return value is `+Inf'. absolute value of X is 1 the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: pow10, Next: pow2, Prev: pow, Up: Alphabetical List pow10 ===== Syntax ------ #include <math.h> double pow10(double x); Description ----------- This function computes 10 to the power of X, 10^x. Return Value ------------ 10 to the X power. If the value of X is finite, but so large in magnitude that 10^x cannot be accurately represented by a `double', the return value is the nearest representable ! `double' (possibly, an `Inf'), and `errno' is set to `ERANGE'. If X is either a positive or a negative infinity, the result is either `+Inf' or zero, respectively, and `errno' is not changed. If X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: pow2, Next: powi, Prev: pow10, Up: Alphabetical List pow2 ==== Syntax ------ #include <math.h> double pow2(double x); Description ----------- This function computes 2 to the power of X, 2^x. Return Value ------------ 2 to the X power. If the value of X is finite, but so large in magnitude that 2^x cannot be accurately represented by a `double', the return value is the nearest representable `double' (possibly, an `Inf'), and `errno' is set to `ERANGE'. If X is either a positive or a negative infinity, the result is either `+Inf' or zero, respectively, and `errno' is not changed. If X is a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: powi, Next: _preserve_fncase, Prev: pow2, Up: Alphabetical List powi ==== Syntax ------ #include <math.h> double powi(double x, int iy); Description ----------- This function computes x^iy, where IY is an integer number. It does so by an optimized sequence of squarings and multiplications. For integer values of exponent, it is always faster to call `powi' than to call `pow' with the same arguments, even if IY has a very large value. For small values of IY, `powi' is *much* faster than `pow'. Return Value ------------ X raised to the IY power. If X and IY are both zero, the return value is 1. If X is equal to zero, and IY is negative, the return value is `Inf'. This function never sets `errno'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _preserve_fncase, Next: printf, Prev: powi, Up: Alphabetical List _preserve_fncase ================ Syntax ------ #include <fcntl.h> char _preserve_fncase (void); Description ----------- This function returns a non-zero value if letter-case in filenames should be preserved. It is used by library functions that get filenames from the operating system (like `readdir', `_fixpath' and others). The usual behavior of these functions (when `_preserve_fncase' returns zero) is to down-case 8+3 DOS-style filenames, but leave alone the letter-case in long filenames when these are supported (*note _use_lfn::.). This can be changed by either setting `_CRT0_FLAG_PRESERVE_FILENAME_CASE' bit in the `_crt0_startup_flags' variable (*note _crt0_startup_flags::.), or by setting the `FNCASE' environment variable to `Y' at run time. You might need such a setup e.g. on Windows 95 if you want to see files with names like `README' and `FAQ' listed in upper-case (for this to work, you will have to manually rename all the other files with 8+3 DOS-style names to lower-case names). When the case in filenames is preserved, all filenames will be returned in upper case on MSDOS (and other systems that don't support long filenames), or if the environment variable `LFN' is set to `N' on systems that support LFN. That is because this is how filenames are stored in the DOS directory entries. Return value ------------ Zero when 8+3 filenames should be converted to lower-case, non-zero otherwise. Portability ----------- not ANSI, not POSIX File: libc.info, Node: printf, Next: psignal, Prev: _preserve_fncase, Up: Alphabetical List printf ====== Syntax ------ #include <stdio.h> int printf(const char *format, ...); Description ----------- Sends formatted output from the arguments (...) to `stdout'. The format string contains regular characters to print, as well as conversion specifiers, which begin with a percent symbol. Each conversion speficier contains the following fields: * an optional flag, which may alter the conversion: `-' left-justify the field. `+' Force a `+' sign on positive numbers. `space' To leave a blank space where a plus or minus sign would have been. `#' Alternate conversion - prefix octal numbers with `0', hexadecimal numbers with `0x' or `0X', or force a trailing decimal point if a floating point conversion would have omitted it. `0' To pad numbers with leading zeros. * A field width specifier, which specifies the minimum width of the field. This may also be an asterisk (`*'), which means that the actual width will be obtained from the next argument. If the argument is negative, it supplies a `-' flag and a positive width. * An optional decimal point and a precision. This may also be an asterisk, but a negative argument for it indicates a precision of zero. The precision specifies the minimum number of digits to print for an integer, the number of fraction digits for a floating point number (max for `g' or `G', actual for others), or the maximum number of characters for a string. * An optional conversion qualifier, which may be `h' to specify `short', `l' to specify long ints, or `L' to specify long doubles. Long long type can be specified by `L' or `ll'. * The conversion type specifier: `c' A single character `d' A signed integer `D' A signed long integer `e' `E' A floating point number (double or long double). The exponent case matches the specifier case. The representation always has an exponent. `f' A floating point number (double or long double). The representation never has an exponent. `g' `G' A floating point number (double or long double). The exponent case matches the specifier case. The representation has an exponent if it needs one. `i' A signed integer. `n' The next argument is a pointer to an integer, and the number of characters generated so far is stored in that integer. `o' A unsigned integer, printed in base 8 instead of base 10. `p' A pointer. This is printed with an `x' specifier. `s' A `NULL'-terminated string. `u' An unsigned integer. `U' An unsigned long integer. `x' `X' An unsigned integer, printed in base 16 instead of base 10. The case of the letters used matches the specifier case. `%' A single percent symbol is printed. Return Value ------------ The number of characters written. Portability ----------- ANSI, POSIX Example ------- printf("%-3d %10.2f%% Percent of %s\n", index, per[index], name[index]); File: libc.info, Node: psignal, Next: _put_path, Prev: printf, Up: Alphabetical List psignal ======= Syntax ------ #include <signal.h> extern char *sys_siglist[]; void psignal (int sig, const char *msg); Description ----------- This function produces a message on the standard error stream describing the signal given by its number in SIG. It prints the string pointed to by MSG, then the name of the signal, and a newline. The names of signals can be retrieved using the array `sys_siglist', with the signal number serving as an index into this array. Portability ----------- not ANSI, not POSIX Example ------- #include <signal.h> void sig_catcher (int sig) { psignal (progname, sig); return; } File: libc.info, Node: _put_path, Next: putc, Prev: psignal, Up: Alphabetical List _put_path ========= Syntax ------ #include <libc/dosio.h> int _put_path(const char *path); int _put_path2(const char *path, int offset); Description ----------- These functions are used internally by all low-level library functions that need to pass file names to DOS. `_put_path' copies its argument PATH to the "transfer buffer" (*note _go32_info_block::.) starting at the beginning of the transfer buffer; `_put_path2' does the same except that it puts the file name starting at OFFSET bytes from the beginning of the transfer buffer. These functions are meant to be called by low-level library functions, not by applications. You should only call them if you know what you are doing. In particular, if you call any library function between a call to `_put_path' or `_put_path2' and the call to a DOS function that uses the file name, the file name in the transfer buffer could be wiped out, corrupted or otherwise changed. You *have* been warned! Some constructs in file names are transformed while copying them, to allow transparent support for nifty features. Here's the list of these transformations: * Multiple forward slashes are collapsed into a single slash. Unix treats multiple slashes as a single slash, so some ported programs pass names like `c:/foo//bar' to library functions. DOS functions choke on such file names, so collapsing the slashes prevents these names from failing. * Trailing slashes are removed, except for root directories. Various DOS calls cannot cope with file names like `c:/foo/'; this feature solves this problem. * Translation of Unix device names. Unix `/dev/null' is mapped to DOS-standard `NUL', and Unix `/dev/tty' to DOS-standard `CON'. This provides for transparent support of these special devices, e.g. in Unix shell scripts. * Translation of DOS device names. Any file name which begins with `/dev/' or `X:/dev/' (where X: is any valid DOS drive letter) has the `/dev/' or `X:/dev/' prefix removed, and the rest is passed to DOS. This is because some DOS functions don't recognize device names unless they are devoid of the drive and directory specifications, and programs could add a drive and a directory if they convert a name like `/dev/con' to a fully-qualified path name. * `/dev/x/' is translated into `x:/'. This allows to use Unix-style absolute path names that begin with a slash, instead of DOS-style names with a drive letter. Some Unix programs and shell scripts fail for file names that include colons, which are part of the drive letter specification; this feature allows to work around such problems by using e.g. `/dev/c/' where `c:/' would fail. * `/dev/env/FOO/' is replaced by the value of the environment variable FOO. (In other words, you can think of environment variables as if they were sub-directories of a fictitious directory `/dev/env'.) This allows to use environment variable names inside path names compiled into programs, and have them transparently expanded at run time. For example, `/dev/env/DJDIR/include' will expand to the exact path name of the DJGPP include directory, no matter where DJGPP is installed on the machine where the program runs. (The value of `DJDIR' is computed by the DJGPP startup code and pushed into the environment of every DJGPP program before `main' is called.) Note that environment variables are case-sensitive, so `/dev/env/foo' and `/dev/env/FOO' are *not* the same. DOS shells usually upcase the name of the environment variable if you set it with the built-in command `SET', so if you type e.g. `SET foo=bar', the shell defines a variable named `FOO'. If the environment variable is undefined, it will expand into an empty string. The expansion is done recursively, so environment variables may reference other environment variables using the same `/dev/env/' notation. For example, if the variable `HOME' is set to `/dev/env/DJDIR/home', and DJGPP is installed in `c:/software/djgpp', then `/dev/env/HOME/sources' will expand to `c:/software/djgpp/home/sources'. It is possible to supply a default value, to be used if the variable is not defined, or has an empty value. To this end, put the default value after the name of the variable and delimit it by `~', like in `/dev/env/DJDIR~c:/djgpp~/include'. If you need to include a literal character `~' in either the environment variable name or in the default value that replaces it, use two `~'s in a row. For example, `/dev/env/FOO~~' will expand to the value of the variable `FOO~'. Likewise, `/dev/env/FOO~~BAR~foo~~baz~' will expand to the value of the variable `FOO~BAR' if it is defined and nonempty, and to `foo~baz' otherwise. Leading `~' in the default value isn't supported (it is interpreted as part of the preceding variable name). The default value may also reference (other) environment variables, but nested default values can get tricky. For example, `/dev/env/foo~/dev/env/bar~' will work, but `/dev/env/foo~/dev/env/bar~baz~~' will *not*. To use nested default values, you need to double the quoting of the `~' characters, like in `/dev/env/foo~/dev/env/bar~~baz~~~'. Return Value ------------ Both functions return the offset into the transfer buffer of the terminating null character that ends the file name. not ANSI, not POSIX Example ------- These functions are meant to be called by low-level library functions, not by applications. You should only call them if you know what you are doing. In particular, if you call any library function between a call to `_put_path' or `_put_path2' and the call to a DOS function that uses the file name, the file name in the transfer buffer could be wiped out, corrupted and otherwise changed. You *have* been warned! __dpmi_regs r; _put_path("/dev/c/djgpp/bin/"); r.x.ax = 0x4300; /* get file attributes */ r.x.ds = __tb >> 4; r.x.dx = __tb & 0x0f; __dpmi_int(0x21, &r); File: libc.info, Node: putc, Next: putch, Prev: _put_path, Up: Alphabetical List putc ==== Syntax ------ #include <stdio.h> int putc(int c, FILE *file); Description ----------- This function writes one character to the given FILE. Return Value ------------ The character written. Portability ----------- ANSI, POSIX Example ------- while ((c=getc(stdin)) != EOF) putc(c, stdout); File: libc.info, Node: putch, Next: putchar, Prev: putc, Up: Alphabetical List putch ===== Syntax ------ #include <conio.h> int putch(int _c); Description ----------- Put the character _C on the screen at the current cursor position. The special characters return, linefeed, bell, and backspace are handled properly, as is line wrap and scrolling. The cursor position is updated. Return Value ------------ The character is returned. Portability ----------- not ANSI, not POSIX File: libc.info, Node: putchar, Next: putenv, Prev: putch, Up: Alphabetical List putchar ======= Syntax ------ #include <stdio.h> int putchar(int c); Description ----------- This is the same as `fputc(c, stdout)'. *Note fputc::. Return Value ------------ The character written. Portability ----------- ANSI, POSIX Example ------- while ((c = getchar()) != EOF) putchar(c); File: libc.info, Node: putenv, Next: puts, Prev: putchar, Up: Alphabetical List putenv ====== Syntax ------ #include <stdlib.h> int putenv(const char *env); Description ----------- This function adds an entry to the program's environment. The string passed must be of the form `NAME'=`VALUE'. Any existing value for the environment variable is gone. `putenv' will copy the string passed to it, and will automatically free any existing string already in the environment. Keep this in mind if you alter the environment yourself. The string you pass is still your responsibility to free. Note that most implementations will not let you free the string you pass, resulting in memory leaks. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- putenv("SHELL=ksh.exe"); File: libc.info, Node: puts, Next: puttext, Prev: putenv, Up: Alphabetical List puts ==== Syntax ------ #include <stdio.h> int puts(const char *string); Description ----------- This function writes STRING to `stdout', and then writes a newline character. Return Value ------------ Nonnegative for success, or `EOF' on error. Portability ----------- ANSI, POSIX Example ------- puts("Hello, there"); File: libc.info, Node: puttext, Next: putw, Prev: puts, Up: Alphabetical List puttext ======= Syntax ------ #include <conio.h> int puttext(int _left, int _top, int _right, int _bottom, void *_source); Description ----------- The opposite of *Note gettext::. Return Value ------------ 1 on success, zero on error. Portability ----------- not ANSI, not POSIX File: libc.info, Node: putw, Next: qsort, Prev: puttext, Up: Alphabetical List putw ==== Syntax ------ #include <stdio.h> int putw(int x, FILE *file); Description ----------- Writes a single binary word in native format to FILE. Return Value ------------ The value written, or `EOF' for end-of-file or error. Since `EOF' is a valid integer, you should use `feof' or `ferror' to detect this situation. Portability ----------- not ANSI, not POSIX Example ------- putw(12, stdout); File: libc.info, Node: qsort, Next: raise, Prev: putw, Up: Alphabetical List qsort ===== Syntax ------ #include <stdlib.h> void qsort(void *base, size_t numelem, size_t size, int (*cmp)(const void *e1, const void *e2)); Description ----------- This function sorts the given array in place. BASE is the address of the first of NUMELEM array entries, each of size SIZE bytes. `qsort' uses the supplied function CMP to determine the sort order for any two elements by passing the address of the two elements and using the function's return address. The return address of the function indicates the sort order: Negative Element E1 should come before element E2 in the resulting array. Positive Element E1 should come after element E2 in the resulting array. Zero It doesn't matter which element comes first in the resulting array. Return Value ------------ None. Portability ----------- ANSI, POSIX Example ------- typedef struct { int size; int sequence; } Item; int qsort_helper_by_size(const void *e1, const void *e2) { return ((const Item *)e2)->size - ((const Item *)e1)->size; } Item list[100]; qsort(list, 100, sizeof(Item), qsort_helper_by_size); int qsort_stringlist(const void *e1, const void *e2) { return strcmp(*(char **)e1, *(char **)e2); } char *slist[10]; /* alphabetical order */ qsort(slist, 10, sizeof(char *), qsort_stringlist); File: libc.info, Node: raise, Next: rand, Prev: qsort, Up: Alphabetical List raise ===== Syntax ------ #include <signal.h> int raise(int sig); Description ----------- This function raises the given signal SIG. *Note the list of possible signals: signal. Return Value ------------ 0 on success, -1 for illegal value of SIG. Portability ----------- ANSI, POSIX File: libc.info, Node: rand, Next: rand48, Prev: raise, Up: Alphabetical List rand ==== Syntax ------ #include <stdlib.h> int rand(void); Description ----------- Returns a pseudo-random number between zero and `RAND_MAX' (defined on `stdlib.h'). By default, this function always generates the same sequence of numbers each time you run the program. (This is usually desirable when debugging, or when comparing two different runs.) If you need to produce a different sequence on every run, you must seed `rand' by calling `srand' (*note srand::.) before the first call to `rand', and make sure to use a different argument to `srand' each time. The usual technique is to get the argument to `srand' from a call to the `time' library function (*note time::.), whose return value changes every second. To get a random number in the range 0..N, use `rand()%(N+1)'. Note that the low bits of the `rand''s return value are not very random, so `rand()%N' for small values of N could be not enough random. The alternative, but non-ANSI, function `random' is better if N is small. *Note random::. Return Value ------------ The number. Portability ----------- ANSI, POSIX Example ------- /* random pause */ srand(time(0)); for (i=rand(); i; i--); File: libc.info, Node: rand48, Next: random, Prev: rand, Up: Alphabetical List rand48 ====== Syntax ------ #include <stdlib.h> double drand48(void); double erand48(unsigned short state[3]); unsigned long lrand48(void); unsigned long nrand48(unsigned short state[3]); long mrand48(void); long jrand48(unsigned short state[3]); void srand48(long seed); unsigned short *seed48(unsigned short state_seed[3]); void lcong48(unsigned short param[7]); Description ----------- This is the family of `*rand48' functions. The basis for these functions is the linear congruential formula X[n+1] = (a*X[n] + c) mod 2^48, n >= 0. a = 0x5deece66d and c = 0xb at start and after a call to either `srand48' or `seed48'. A call to `lcong48' changes a and c (and the internal state). `drand48' and `erand48' return `double's uniformly distributed in the interval [0.0, 1.0). `lrand48' and `nrand48' return `unsigned long's uniformly distributed in the interval [0, 2^31). `mrand48' and `jrand48' return `long's uniformly distributed in the interval [-2^31, 2^31). `erand48', `jrand48' and `nrand48' requires the state of the random generator to be passed. `drand48', `lrand48' and `mrand48' uses an internal state (common with all three functions) which should be initialized with a call to one of the functions `srand48', `seed48' or `lcong48'. `srand48' sets the high order 32 bits to the argument SEED. The low order 16 bits are set to the arbitrary value 0x330e. `seed48' sets the internal state according to the argument STATE_SEED (`STATE_SEED[0]' is least significant). The previous state of the random generator is saved in an internal (static) buffer, to which a pointer is returned. `lcong48' sets the internal state to `PARAM[0-2]', a to `PARAM[3-5]' (`PARAM[0]' and `PARAM[3]' are least significant) and c to `PARAM[6]'. Return Value ------------ A random number. Portability ----------- not ANSI, not POSIX Example ------- #include <stdio.h> #include <stdlib.h> #include <time.h> int main(void) { srand48(time(NULL)); printf("%.12f is a random number in [0.0, 1.0).\n", drand48()); exit(0); } File: libc.info, Node: random, Next: rawclock, Prev: rand48, Up: Alphabetical List random ====== Syntax ------ #include <stdlib.h> long random(void); Description ----------- Returns a random number in the range 0..MAXINT. Return Value ------------ 0 .. MAXINT Portability ----------- not ANSI, not POSIX Example ------- /* Produce a random integer between 0 and 199. */ int random_number = random () % 200; File: libc.info, Node: rawclock, Next: read, Prev: random, Up: Alphabetical List rawclock ======== Syntax ------ #include <time.h> unsigned long rawclock(void); Description ----------- Returns the number of clock tics (18.2 per second) since midnight. Return Value ------------ The number of tics. Portability ----------- not ANSI, not POSIX Example ------- /* wait 1/4 second */ int i = rawclock()+5; while (rawclock()<i); File: libc.info, Node: read, Next: _read, Prev: rawclock, Up: Alphabetical List read ==== Syntax ------ #include <unistd.h> ssize_t read(int fd, void *buffer, size_t length); Description ----------- This function reads at most LENGTH bytes from file FD into BUFFER. Note that in some cases, such as end-of-file conditions and text files, it may read less than the requested number of bytes. At end-of-file, `read' will read exactly zero bytes. Return Value ------------ The number of bytes read, zero meaning end-of-file, or -1 for an error. Portability ----------- not ANSI, POSIX Example ------- char buf[10]; int r = read(0, buf, 10); File: libc.info, Node: _read, Next: read_child, Prev: read, Up: Alphabetical List _read ===== Syntax ------ #include <io.h> ssize_t _read(int fildes, void *buf, size_t nbyte); Description ----------- This is a direct connection to the MS-DOS read function call, int 0x21, %ah = 0x3f. No conversion is done on the data; it is read as raw binary data. This function can be hooked by the *Note File System Extensions::. If you don't want this, you should use *Note _dos_read::. Return Value ------------ The number of bytes read. Portability ----------- not ANSI, not POSIX File: libc.info, Node: read_child, Next: read_sel_addr, Prev: _read, Up: Alphabetical List read_child ========== Syntax ------ #include <debug/dbgcom.h> void read_child (unsigned child_addr, void *buf, unsigned len); Description ----------- This function reads the memory of the debugged process starting at address CHILD_ADDR for LEN bytes, and copies the data read to the buffer pointed to by BUF. It is used primarily to save the original instruction at the point where a breakpoint instruction is inserted (to trigger a trap when the debuggee's code gets to that point). *Note write_child::. Return Value ------------ The function return zero if it has successfully transferred the data, non-zero otherwise (e.g., if the address in CHILD_ADDR is outside the limits of the debuggee's code segment. Portability ----------- not ANSI, not POSIX File: libc.info, Node: read_sel_addr, Next: readdir, Prev: read_child, Up: Alphabetical List read_sel_addr ============= Syntax ------ #include <debug/dbgcom.h> void read_sel_addr (unsigned offset, void *buf, unsigned len, unsigned sel); Description ----------- This function reads the memory starting at offset OFFSET in selector SEL for LEN bytes, and copies the data read to the buffer pointed to by BUF. *Note write_sel_addr::. Return Value ------------ The function return zero if it has successfully transferred the data, non-zero otherwise (e.g., if the address in OFFSET is outside the limits of the segment whose selector is SEL). Portability ----------- not ANSI, not POSIX File: libc.info, Node: readdir, Next: realloc, Prev: read_sel_addr, Up: Alphabetical List readdir ======= Syntax ------ #include <dirent.h> struct dirent *readdir(DIR *dir); Description ----------- This function reads entries from a directory opened by `opendir' (*note opendir::.). It returns the information in a static buffer with this format: struct dirent { unsigned short d_namlen; /* The length of the name (like strlen) */ char d_name[MAXNAMLEN+1]; /* The name */ }; Note that some directory entries might be skipped by `readdir', depending on the bits set in the global variable `__opendir_flags'. *Note __opendir_flags: opendir. Return Value ------------ A pointer to a static buffer that is overwritten with each call. Portability ----------- not ANSI, POSIX (see note 1) Notes: 1. The `__opendir_flags' variable is DJGPP-specific. Example ------- DIR *d = opendir("."); struct dirent *de; while (de = readdir(d)) puts(de->d_name); closedir(d); File: libc.info, Node: realloc, Next: redir_cmdline_delete, Prev: readdir, Up: Alphabetical List realloc ======= Syntax ------ #include <stdlib.h> void *realloc(void *ptr, size_t size); Description ----------- This function changes the size of the region pointed to by PTR. If it can, it will reuse the same memory space, but it may have to allocate a new memory space to satisfy the request. In either case, it will return the pointer that you should use to refer to the (possibly new) memory area. The pointer passed may be `NULL', in which case this function acts just like `malloc' (*note malloc::.). Return Value ------------ A pointer to the memory you should now refer to. Portability ----------- ANSI, POSIX Example ------- if (now+new > max) { max = now+new; p = realloc(p, max); } File: libc.info, Node: redir_cmdline_delete, Next: redir_cmdline_parse, Prev: realloc, Up: Alphabetical List redir_cmdline_delete ==================== Syntax ------ #include <debug/redir.h> void redir_cmdline_delete (cmdline_t *cmd); Description ----------- For the rationale and general description of the debugger redirection issue, see *Note redir_debug_init::. This function serves as a destructor for a `cmdline_t' object. It frees storage used for the command-line arguments associated with CMD, closes any open handles stored in it, and frees memory used to store the file handles and the file names of the files where standard handles were redirected. The function is safe to use even if CMD might be a `NULL' pointer, or if some of members of the `cmdline_t' structure are `NULL' pointers. *Note redir_debug_init::, for detailed description of the `cmdline_t' structure. Portability ----------- not ANSI, not POSIX Example ------- redir_cmdline_delete (&child_cmd); File: libc.info, Node: redir_cmdline_parse, Next: redir_debug_init, Prev: redir_cmdline_delete, Up: Alphabetical List redir_cmdline_parse =================== Syntax ------ #include <debug/redir.h> int redir_cmdline_parse (const char *args, cmdline_t *cmd); Description ----------- For the rationale and general description of the debugger redirection issue, see *Note redir_debug_init::. This function parses a command-line tail (i.e., without the program to be invoked) passed as a string in ARGS. For every redirection directive in ARGS, like `>> foo', it opens the file that is the target of the redirection, and records in CMD the information about these redirections. (*Note redir_debug_init::, for details of the `cmdline_t' structure that is used to hold this information.) The command line with redirections removed is placed into `cmd->command' (typically, it will be used to call `v2loadimage', *note v2loadimage::.), while the rest of information is used by `redir_to_child' and `redir_to_debugger' to redirect standard handles before and after calling `run_child'. Return Value ------------ The function returns zero in case of success, -1 otherwise. Failure usually means some kind of syntax error, like `>' without a file name following it; or a file name that isn't allowed by the underlying OS, like `lost+found' on DOS. Portability ----------- not ANSI, not POSIX Example ------- /* Init command line storage. */ if (redir_debug_init (&child_cmd) == -1) fatal ("Cannot allocate redirection storage: not enough memory.\n"); /* Parse the command line and create redirections. */ if (strpbrk (args, "<>")) { if (redir_cmdline_parse (args, &child_cmd) == 0) args = child_cmd.command; else error ("Syntax error in command line."); } else child_cmd.command = strdup (args); cmdline = (char *) alloca (strlen (args) + 4); cmdline[0] = strlen (args); strcpy (cmdline + 1, args); cmdline[strlen (args) + 1] = 13; if (v2loadimage (exec_file, cmdline, start_state)) { printf ("Load failed for image %s\n", exec_file); exit (1); } File: libc.info, Node: redir_debug_init, Next: redir_to_child, Prev: redir_cmdline_parse, Up: Alphabetical List redir_debug_init ================ Syntax ------ #include <debug/redir.h> int redir_debug_init (cmdline_t *cmd); Description ----------- This function initializes the data structure in the CMD variable required to save and restore debugger's standard handles across invocations of `run_child' (*note run_child::.). The debugger will then typically call `redir_to_child' and `redir_to_debugger'. These functions are needed when a debugger wants to redirect standard handles of the debuggee, or if the debuggee redirects some of its standard handles, because the debuggee is not a separate process, we just pretend it is by jumping between two threads of execution. But, as far as DOS is concerned, the debugger and the debuggee are a single process, and they share the same "Job File Table" (JFT). The JFT is a table maintained by DOS in the program's PSP where, for each open handle, DOS stores the index into the SFT, the "System File Table". (The SFT is an internal data structure where DOS maintains everything it knows about a certain open file/device.) A handle that is returned by `open', `_open' and other similar functions is simply an index into the JFT where DOS stored the SFT entry index for the file or device that the program opened. When a program starts, the first 5 entries in the JFT are preconnected to the standard devices. Any additional handles opened by either the debugger or the debuggee use handles beyond the first 5 (unless one of the preconnected handles is deliberately closed). Here we mostly deal with handles 0, 1 and 2, the standard input, standard output, and standard error; they all start connected to the console device (unless somebody redirects the debugger's I/O from the command line). Since both the debugger and the debuggee share the same JFT, their handles 0, 1 and 2 point to the same JFT entries and thus are connected to the same files/devices. Therefore, if the debugger redirects its standard output, the standard output of the debuggee is also automagically redirected to the same file/device! Similarly, if the debuggee redirects its stdout to a file, you won't be able to see debugger's output (it will go to the same file where the debuggee has its output); and if the debuggee closes its standard input, you will lose the ability to talk to debugger! The debugger redirection support attempts to solve all these problems by creating an illusion of two separate sets of standard handles. Each time the debuggee is about to be run or resumed, it should call `redir_to_child' to redirect debugger's own standard handles to the file specified in the command-line (as given by e.g. the "run" command of GDB) before running the debuggee, then call `redir_to_debugger' to redirect them back to the debugger's original input/output when the control is returned from the debuggee (e.g. after a breakpoint is hit). Although the debugger and the debuggee have two separate copies of the file-associated data structures, the debugger still can redirect standard handles of the debuggee because they use the same JFT entries as debugger's own standard handles. The `cmdline_t' structure is declared in the header `debug/redir.h' as follows: struct dbg_redirect { int inf_handle; /* debuggee's handle */ int our_handle; /* debugger's handle */ char *file_name; /* file name where debuggee's handle is redirected */ int mode; /* mode used to open() the above file */ off_t filepos; /* file position of debuggee's handle; unused */ }; typedef struct _cmdline { char *command; /* command line with redirection removed */ int redirected; /* 1 if handles redirected for child */ struct dbg_redirect **redirection;/* info about redirected handles */ } cmdline_t; In the `cmdline_t' structure, the `redirection' member points to an array of 3 `dbg_redirect' structures, one each for each one of the 3 standard handles. The `inf_handle' and `our_handle' members of those structures are used to save the handle used, respectively, by the debuggee (a.k.a. "the inferior process") and by the debugger. The CMD variable is supposed to be defined by the debugger's application code. `redir_debug_init' is called to initialize that variable. It calls `redir_cmdline_delete' to close any open handles held in CMD and to free any allocated storage; then it fills CMD with the trivial information (i.e., every standard stream is connected to the usual handles 0, 1, and 2). Return Value ------------ `redir_debug_init' returns zero in case of success, or -1 otherwise. Portability ----------- not ANSI, not POSIX Example ------- if (redir_debug_init (&child_cmd) == -1) fatal ("Cannot allocate redirection storage: not enough memory.\n"); File: libc.info, Node: redir_to_child, Next: redir_to_debugger, Prev: redir_debug_init, Up: Alphabetical List redir_to_child ============== Syntax ------ #include <debug/redir.h> int redir_to_child (cmdline_t *cmd); Description ----------- For the rationale and general description of the debugger redirection issue, see *Note redir_debug_init::. This function redirects all 3 standard streams so that they point to the files/devices where the child (a.k.a. debuggee) process connected them. All three standard handles point to the console device by default, but this could be changed, either because the command line for the child requested redirection, like in `prog > foo', or because the child program itself redirected one of its standard handles e.g. with a call to `dup2'. `redir_to_child' uses information stored in the `cmdline_t' variable pointed to by the CMD argument to redirect the standard streams as appropriate for the debuggee, while saving the original debugger's handles to be restored by `redir_to_debugger'. Return Value ------------ The function returns zero in case of success, -1 in case of failure. Failure usually means the process has run out of available file handles. Portability ----------- not ANSI, not POSIX Example ------- errno = 0; if (redir_to_child (&child_cmd) == -1) { redir_to_debugger (&child_cmd); error ("Cannot redirect standard handles for program: %s.", strerror (errno)); } File: libc.info, Node: redir_to_debugger, Next: regcomp, Prev: redir_to_child, Up: Alphabetical List redir_to_debugger ================= Syntax ------ #include <debug/redir.h> int redir_to_debugger (cmdline_t *cmd); Description ----------- For the rationale and general description of the debugger redirection issue, see *Note redir_debug_init::. This function redirects all 3 standard streams so that they point to the files/devices where the debugger process connected them. All three standard handles point to the console device by default, but this could be changed, either because the command line for the child requested redirection, like in `prog > foo', or because the child program itself redirected one of its standard handles e.g. with a call to `dup2'. `redir_to_debugger' uses information stored in the `cmdline_t' variable pointed to by the CMD argument to redirect the standard streams as appropriate for the debugger, while saving the original debuggee's handles to be restored by `redir_to_child'. Return Value ------------ The function returns zero in case of success, -1 in case of failure. Failure usually means the process has run out of available file handles. Portability ----------- not ANSI, not POSIX Example ------- /* Restore debugger's standard handles. */ errno = 0; if (redir_to_debugger (&child_cmd) == -1) error ("Cannot redirect standard handles for debugger: %s.", strerror (errno)); File: libc.info, Node: regcomp, Next: regerror, Prev: redir_to_debugger, Up: Alphabetical List regcomp ======= Syntax ------ #include <sys/types.h> #include <regex.h> int regcomp(regex_t *preg, const char *pattern, int cflags); Description ----------- This function is part of the implementation of POSIX 1003.2 regular expressions ("RE"s). `regcomp' compiles the regular expression contained in the PATTERN string, subject to the flags in CFLAGS, and places the results in the `regex_t' structure pointed to by PREG. (The regular expression syntax, as defined by POSIX 1003.2, is described below.) The parameter CFLAGS is the bitwise OR of zero or more of the following flags: `REG_EXTENDED' Compile modern ("extended") REs, rather than the obsolete ("basic") REs that are the default. `REG_BASIC' This is a synonym for 0, provided as a counterpart to `REG_EXTENDED' to improve readability. This is an extension, compatible with but not specified by POSIX 1003.2, and should be used with caution in software intended to be portable to other systems. `REG_NOSPEC' Compile with recognition of all special characters turned off. All characters are thus considered ordinary, so the RE in PATTERN is a literal string. This is an extension, compatible with but not specified by POSIX 1003.2, and should be used with caution in software intended to be portable to other systems. `REG_EXTENDED' and `REG_NOSPEC' may not be used in the same call to `regcomp'. `REG_ICASE' Compile for matching that ignores upper/lower case distinctions. See the description of regular expressions below for details of case-independent matching. `REG_NOSUB' Compile for matching that need only report success or failure, not what was matched. `REG_NEWLINE' Compile for newline-sensitive matching. By default, newline is a completely ordinary character with no special meaning in either REs or strings. With this flag, `[^' bracket expressions and `.' never match newline, a `^' anchor matches the null string after any newline in the string in addition to its normal function, and the `$' anchor matches the null string before any newline in the string in addition to its normal function. `REG_PEND' The regular expression ends, not at the first NUL, but just before the character pointed to by the `re_endp' member of the structure pointed to by PREG. The `re_endp' member is of type `const char *'. This flag permits inclusion of NULs in the RE; they are considered ordinary characters. This is an extension, compatible with but not specified by POSIX 1003.2, and should be used with caution in software intended to be portable to other systems. When successful, `regcomp' returns 0 and fills in the structure pointed to by PREG. One member of that structure (other than `re_endp') is publicized: `re_nsub', of type `size_t', contains the number of parenthesized subexpressions within the RE (except that the value of this member is undefined if the `REG_NOSUB' flag was used). Note that the length of the RE does matter; in particular, there is a strong speed bonus for keeping RE length under about 30 characters, with most special characters counting roughly double. Return Value ------------ If `regcomp' succeeds, it returns zero; if it fails, it returns a non-zero error code, which is one of these: `REG_BADPAT' invalid regular expression `REG_ECOLLATE' invalid collating element `REG_ECTYPE' invalid character class `REG_EESCAPE' `\' applied to unescapable character `REG_ESUBREG' invalid backreference number (e.g., larger than the number of parenthesized subexpressions in the RE) `REG_EBRACK' brackets [ ] not balanced `REG_EPAREN' parentheses ( ) not balanced `REG_EBRACE' braces { } not balanced `REG_BADBR' invalid repetition count(s) in { } `REG_ERANGE' invalid character range in [ ] `REG_ESPACE' ran out of memory (an RE like, say, `((((a{1,100}){1,100}){1,100}){1,100}){1,100}'' will eventually run almost any existing machine out of swap space) `REG_BADRPT' ?, *, or + operand invalid `REG_EMPTY' empty (sub)expression `REG_ASSERT' "can't happen" (you found a bug in `regcomp') `REG_INVARG' invalid argument (e.g. a negative-length string) Regular Expressions' Syntax --------------------------- Regular expressions ("RE"s), as defined in POSIX 1003.2, come in two forms: modern REs (roughly those of `egrep'; 1003.2 calls these *extended* REs) and obsolete REs (roughly those of `ed'; 1003.2 *basic* REs). Obsolete REs mostly exist for backward compatibility in some old programs; they will be discussed at the end. 1003.2 leaves some aspects of RE syntax and semantics open; `(*)' marks decisions on these aspects that may not be fully portable to other 1003.2 implementations. A (modern) RE is one(*) or more non-empty(*) *branches*, separated by `|'. It matches anything that matches one of the branches. A branch is one(*) or more *pieces*, concatenated. It matches a match for the first, followed by a match for the second, etc. A piece is an *atom* possibly followed by a single(*) `*', `+', `?', or *bound*. An atom followed by `*' matches a sequence of 0 or more matches of the atom. An atom followed by `+' matches a sequence of 1 or more matches of the atom. An atom followed by `?' matches a sequence of 0 or 1 matches of the atom. A *bound* is `{' followed by an unsigned decimal integer, possibly followed by `,' possibly followed by another unsigned decimal integer, always followed by `}'. The integers must lie between 0 and `RE_DUP_MAX' (255(*)) inclusive, and if there are two of them, the first may not exceed the second. An atom followed by a bound containing one integer `i' and no comma matches a sequence of exactly `i' matches of the atom. An atom followed by a bound containing one integer `i' and a comma matches a sequence of `i' or more matches of the atom. An atom followed by a bound containing two integers `i' and `j' matches a sequence of `i' through `j' (inclusive) matches of the atom. An atom is a regular expression enclosed in `()' (matching a match for the regular expression), an empty set of `()' (matching the null string(*)), a *bracket expression* (see below), `.' (matching any single character), `^' (matching the null string at the beginning of a line), `$' (matching the null string at the end of a line), a `\' followed by one of the characters `^.[$()|*+?{\\' (matching that character taken as an ordinary character), a `\' followed by any other character(*) (matching that character taken as an ordinary character, as if the `\' had not been present(*)), or a single character with no other significance (matching that character). A `{' followed by a character other than a digit is an ordinary character, not the beginning of a bound(*). It is illegal to end an RE with `\'. A *bracket expression* is a list of characters enclosed in `[]'. It normally matches any single character from the list (but see below). If the list begins with `^', it matches any single character (but see below) *not* from the rest of the list. If two characters in the list are separated by `-', this is shorthand for the full *range* of characters between those two (inclusive) in the collating sequence, e.g. `[0-9]' in ASCII matches any decimal digit. It is illegal(*) for two ranges to share an endpoint, e.g. `a-c-e'. Ranges are very collating-sequence-dependent, and portable programs should avoid relying on them. To include a literal `]' in the list, make it the first character (following a possible `^'). To include a literal `-', make it the first or last character, or the second endpoint of a range. To use a literal `-' as the first endpoint of a range, enclose it in `[.' and `.]' to make it a collating element (see below). With the exception of these and some combinations using `[' (see next paragraphs), all other special characters, including `\', lose their special significance within a bracket expression. Within a bracket expression, a collating element (a character, a multi-character sequence that collates as if it were a single character, or a collating-sequence name for either) enclosed in `[.' and `.]' stands for the sequence of characters of that collating element. The sequence is a single element of the bracket expression's list. A bracket expression containing a multi-character collating element can thus match more than one character, e.g. if the collating sequence includes a `ch' collating element, then the RE `[[.ch.]]*c' matches the first five characters of "chchcc". Within a bracket expression, a collating element enclosed in `[=' and `=]' is an equivalence class, standing for the sequences of characters of all collating elements equivalent to that one, including itself. (If there are no other equivalent collating elements, the treatment is as if the enclosing delimiters were `[.' and `.]'.) For example, if `o' and `^' are the members of an equivalence class, then `[[=o=]]', `[[=^=]]', and `[o^]' are all synonymous. An equivalence class may *not* be an endpoint of a range. Within a bracket expression, the name of a *character class* enclosed in `[:' and `:]' stands for the list of all characters belonging to that class. Standard character class names are: alnum digit punct alpha graph space blank lower upper cntrl print xdigit These stand for the character classes defined by `isalnum' (*note isalnum::.), `isdigit' (*note isdigit::.), `ispunct' (*note ispunct::.), `isalpha' (*note isalpha::.), `isgraph' (*note isgraph::.), `isspace' (*note isspace::.) (`blank' is the same as `space'), `islower' (*note islower::.), `isupper' (*note isupper::.), `iscntrl' (*note iscntrl::.), `isprint' (*note isprint::.), and `isxdigit' (*note isxdigit::.), respectively. A locale may provide others. A character class may not be used as an endpoint of a range. There are two special cases(*) of bracket expressions: the bracket expressions `[[:<:]]' and `[[:>:]]' match the null string at the beginning and end of a word respectively. A word is defined as a sequence of word characters which is neither preceded nor followed by word characters. A word character is an `alnum' character (as defined by `isalnum' library function) or an underscore. This is an extension, compatible with but not specified by POSIX 1003.2, and should be used with caution in software intended to be portable to other systems. In the event that an RE could match more than one substring of a given string, the RE matches the one starting earliest in the string. If the RE could match more than one substring starting at that point, it matches the longest. Subexpressions also match the longest possible substrings, subject to the constraint that the whole match be as long as possible, with subexpressions starting earlier in the RE taking priority over ones starting later. Note that higher-level subexpressions thus take priority over their lower-level component subexpressions. Match lengths are measured in characters, not collating elements. A null string is considered longer than no match at all. For example, `bb*' matches the three middle characters of "abbbc", `(wee|week)(knights|nights)' matches all ten characters of "weeknights", when `(.*).*' is matched against "abc" the parenthesized subexpression matches all three characters, and when `(a*)*' is matched against "bc" both the whole RE and the parenthesized subexpression match the null string. If case-independent matching is specified, the effect is much as if all case distinctions had vanished from the alphabet. When an alphabetic that exists in multiple cases appears as an ordinary character outside a bracket expression, it is effectively transformed into a bracket expression containing both cases, e.g. `x' becomes `[xX]'. When it appears inside a bracket expression, all case counterparts of it are added to the bracket expression, so that (e.g.) `[x]' becomes `[xX]' and `[^x]' becomes `[^xX]'. No particular limit is imposed on the length of REs(*). Programs intended to be portable should not employ REs longer than 256 bytes, as an implementation can refuse to accept such REs and remain POSIX-compliant. Obsolete (*basic*) regular expressions differ in several respects. `|', `+', and `?' are ordinary characters and there is no equivalent for their functionality. The delimiters for bounds are `\{' and `\}', with `{' and `}' by themselves ordinary characters. The parentheses for nested subexpressions are `$' and `$', with `(' and `)' by themselves ordinary characters. `^' is an ordinary character except at the beginning of the RE or(*) the beginning of a parenthesized subexpression, `$' is an ordinary character except at the end of the RE or(*) the end of a parenthesized subexpression, and `*' is an ordinary character if it appears at the beginning of the RE or the beginning of a parenthesized subexpression (after a possible leading `^'). Finally, there is one new type of atom, a *back reference*: `\' followed by a non-zero decimal digit *d* matches the same sequence of characters matched by the *d*th parenthesized subexpression (numbering subexpressions by the positions of their opening parentheses, left to right), so that (e.g.) `$[bc]$\1' matches "bb" or "cc" but not "bc". History ------- This implementation of the POSIX regexp functionality was written by Henry Spencer <henry@zoo.toronto.edu>. Bugs ---- The locale is always assumed to be the default one of 1003.2, and only the collating elements etc. of that locale are available. `regcomp' implements bounded repetitions by macro expansion, which is costly in time and space if counts are large or bounded repetitions are nested. An RE like, say, `((((a{1,100}){1,100}){1,100}){1,100}){1,100}', will (eventually) run almost any existing machine out of swap space. There are suspected problems with response to obscure error conditions. Notably, certain kinds of internal overflow, produced only by truly enormous REs or by multiply nested bounded repetitions, are probably not handled well. Due to a mistake in 1003.2, things like `a)b' are legal REs because `)' is a special character only in the presence of a previous unmatched `('. This can't be fixed until the spec is fixed. The standard's definition of back references is vague. For example, does `a\e(\e(b\e)*\e2\e)*d' match "abbbd"? Until the standard is clarified, behavior in such cases should not be relied on. Portability ----------- not ANSI, POSIX File: libc.info, Node: regerror, Next: regexec, Prev: regcomp, Up: Alphabetical List regerror ======== Syntax ------ #include <sys/types.h> #include <regex.h> size_t regerror(int errcode, const regex_t *preg, char *errbuf, size_t errbuf_size); Description ----------- `regerror' maps a non-zero value of ERRCODE from either `regcomp' (Return Value, *note regcomp::.) or `regexec' (Return Value, *note regexec::.) to a human-readable, printable message. If PREG is non-`NULL', the error code should have arisen from use of the variable of the type `regex_t' pointed to by PREG, and if the error code came from `regcomp', it should have been the result from the most recent `regcomp' using that `regex_t' variable. (`regerror' may be able to supply a more detailed message using information from the `regex_t' than from ERRCODE alone.) `regerror' places the `NUL'-terminated message into the buffer pointed to by ERRBUF, limiting the length (including the `NUL') to at most ERRBUF_SIZE bytes. If the whole message won't fit, as much of it as will fit before the terminating `NUL' is supplied. In any case, the returned value is the size of buffer needed to hold the whole message (including terminating `NUL'). If ERRBUF_SIZE is 0, ERRBUF is ignored but the return value is still correct. If the ERRCODE given to `regerror' is first ORed with `REG_ITOA', the "message" that results is the printable name of the error code, e.g. "REG_NOMATCH", rather than an explanation thereof. If ERRCODE is `REG_ATOI', then PREG shall be non-NULL and the `re_endp' member of the structure it points to must point to the printable name of an error code (e.g. "REG_ECOLLATE"); in this case, the result in ERRBUF is the decimal representation of the numeric value of the error code (0 if the name is not recognized). `REG_ITOA' and `REG_ATOI' are intended primarily as debugging facilities; they are extensions, compatible with but not specified by POSIX 1003.2, and should be used with caution in software intended to be portable to other systems. Be warned also that they are considered experimental and changes are possible. Return Value ------------ The size of buffer needed to hold the message (including terminating `NUL') is always returned, even if ERRBUF_SIZE is zero. Portability ----------- not ANSI, POSIX File: libc.info, Node: regexec, Next: regfree, Prev: regerror, Up: Alphabetical List regexec ======= Syntax ------ #include <sys/types.h> #include <regex.h> int regexec(const regex_t *preg, const char *string, size_t nmatch, regmatch_t pmatch[], int eflags); Description ----------- `regexec' matches the compiled RE pointed to by PREG against the STRING, subject to the flags in EFLAGS, and reports results using NMATCH, PMATCH, and the returned value. The RE must have been compiled by a previous invocation of `regcomp' (*note regcomp::.). The compiled form is not altered during execution of `regexec', so a single compiled RE can be used simultaneously by multiple threads. By default, the NUL-terminated string pointed to by STRING is considered to be the text of an entire line, with the NUL indicating the end of the line. (That is, any other end-of-line marker is considered to have been removed and replaced by the NUL.) The EFLAGS argument is the bitwise OR of zero or more of the following flags: `REG_NOTBOL' The first character of the string is not the beginning of a line, so the `^' anchor should not match before it. This does not affect the behavior of newlines under `REG_NEWLINE' (REG_NEWLINE, *note regcomp::.). `REG_NOTEOL' The NUL terminating the string does not end a line, so the `$' anchor should not match before it. This does not affect the behavior of newlines under `REG_NEWLINE' (REG_NEWLINE, *note regcomp::.). `REG_STARTEND' The string is considered to start at `STRING + PMATCH[0].rm_so' and to have a terminating `NUL' located at `STRING + PMATCH[0].rm_eo' (there need not actually be a `NUL' at that location), regardless of the value of NMATCH. See below for the definition of PMATCH and NMATCH. This is an extension, compatible with but not specified by POSIX 1003.2, and should be used with caution in software intended to be portable to other systems. Note that a non-zero `rm_so' does not imply `REG_NOTBOL'; `REG_STARTEND' affects only the location of the string, not how it is matched. `REG_TRACE' trace execution (printed to stdout) `REG_LARGE' force large representation `REG_BACKR' force use of backref code Regular Expressions' Syntax, *Note regcomp::, for a discussion of what is matched in situations where an RE or a portion thereof could match any of several substrings of STRING. If `REG_NOSUB' was specified in the compilation of the RE (REG_NOSUB, *note regcomp::.), or if NMATCH is 0, `regexec' ignores the PMATCH argument (but see below for the case where `REG_STARTEND' is specified). Otherwise, PMATCH should point to an array of NMATCH structures of type `regmatch_t'. Such a structure has at least the members `rm_so' and `rm_eo', both of type `regoff_t' (a signed arithmetic type at least as large as an `off_t' and a `ssize_t', containing respectively the offset of the first character of a substring and the offset of the first character after the end of the substring. Offsets are measured from the beginning of the STRING argument given to `regexec'. An empty substring is denoted by equal offsets, both indicating the character following the empty substring. When `regexec' returns, the 0th member of the PMATCH array is filled in to indicate what substring of STRING was matched by the entire RE. Remaining members report what substring was matched by parenthesized subexpressions within the RE; member `i' reports subexpression `i', with subexpressions counted (starting at 1) by the order of their opening parentheses in the RE, left to right. Unused entries in the array--corresponding either to subexpressions that did not participate in the match at all, or to subexpressions that do not exist in the RE (that is, `i > preg->re_nsub'--have both `rm_so' and `rm_eo' set to `-1'. If a subexpression participated in the match several times, the reported substring is the last one it matched. (Note, as an example in particular, that when the RE `(b*)+' matches "bbb", the parenthesized subexpression matches the three `b's and then an infinite number of empty strings following the last `b', so the reported substring is one of the empties.) If `REG_STARTEND' is specified in EFLAGS, PMATCH must point to at least one `regmatch_t' variable (even if NMATCH is 0 or `REG_NOSUB' was specified in the compilation of the RE, REG_NOSUB, *note regcomp::.), to hold the input offsets for `REG_STARTEND'. Use for output is still entirely controlled by NMATCH; if NMATCH is 0 or `REG_NOSUB' was specified, the value of `pmatch[0]' will not be changed by a successful `regexec'. Return Value ------------ Normally, `regexec' returns 0 for success and the non-zero code `REG_NOMATCH' for failure. Other non-zero error codes may be returned in exceptional situations. The list of possible error return values is below: `REG_ESPACE' ran out of memory `REG_BADPAT' the passed argument PREG doesn't point to an RE compiled by `regcomp' `REG_INVARG' invalid argument(s) (e.g., `STRING + PMATCH[0].rm_eo' is less than `STRING + PMATCH[0].rm_so') History ------- This implementation of the POSIX regexp functionality was written by Henry Spencer <henry@zoo.toronto.edu>. Bugs ---- `regexec' performance is poor. NMATCH exceeding 0 is expensive; NMATCH exceeding 1 is worse. `regexec' is largely insensitive to RE complexity *except* that back references are massively expensive. RE length does matter; in particular, there is a strong speed bonus for keeping RE length under about 30 characters, with most special characters counting roughly double. The implementation of word-boundary matching is a bit of a kludge, and bugs may lurk in combinations of word-boundary matching and anchoring. Portability ----------- not ANSI, POSIX File: libc.info, Node: regfree, Next: remove, Prev: regexec, Up: Alphabetical List regfree ======= Syntax ------ #include <sys/types.h> #include <regex.h> void regfree(regex_t *preg); Description ----------- `regfree' frees any dynamically-allocated storage associated with the compiled RE pointed to by PREG. The remaining `regex_t' is no longer a valid compiled RE and the effect of supplying it to `regexec' or `regerror' is undefined. Portability ----------- not ANSI, POSIX File: libc.info, Node: remove, Next: remque, Prev: regfree, Up: Alphabetical List remove ====== Syntax ------ #include <stdio.h> int remove(const char *file); Description ----------- This function removes the named FILE from the file system. Unless you have an un-erase program, the file and its contents are gone for good. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- ANSI, POSIX Example ------- remove("/tmp/data.tmp"); File: libc.info, Node: remque, Next: _rename, Prev: remove, Up: Alphabetical List remque ====== Syntax ------ #include <search.h> void remque(struct qelem *elem); Description ----------- This function manipulates queues built from doubly linked lists. Each element in the queue must be in the form of `struct qelem' which is defined thus: struct qelem { struct qelem *q_forw; struct qelem *q_back; char q_data[0]; } This function removes the entry ELEM from a queue. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _rename, Next: rename, Prev: remque, Up: Alphabetical List _rename ======= Syntax ------ #include <stdio.h> int _rename(const char *oldname, const char *newname); Description ----------- This function renames an existing file or directory OLDNAME to NEWNAME. It is much smaller that `rename' (*note rename::.), but it can only rename a directory so it stays under the same parent, it cannot move directories between different branches of the directory tree. This means that in the following example, the first call will succeed, while the second will fail: _rename("c:/path1/mydir", "c:/path1/yourdir"); _rename("c:/path1/mydir", "c:/path2"); On systems that support long filenames (*note _use_lfn::.), `_rename' can also move directories (so that both calls in the above example succeed there), unless the `LFN' environment variable is set to `n', or the `_CRT0_FLAG_NO_LFN' is set in the `_crt0_startup_flags' variable, *Note _crt0_startup_flags::. If you don't need the extra functionality offered by `rename' (which usually is only expected by Unix-born programs), you can use `_rename' instead and thus make your program a lot smaller. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: rename, Next: rewind, Prev: _rename, Up: Alphabetical List rename ====== Syntax ------ #include <stdio.h> int rename(const char *oldname, const char *newname); Description ----------- This function renames an existing file or directory OLDNAME to NEWNAME. If NEWNAME exists, then it is first removed. If NEWNAME is a directory, it must be empty (or else ERRNO will be set to `ENOTEMPTY'), and must not include OLDNAME in its path prefix (otherwise, ERRNO will be set to `EINVAL'). If NEWNAME exists, both OLDNAME and NEWNAME must be of the same type (both directories or both regular files) (or else ERRNO will be set to `ENOTDIR' or `EISDIR'), and must reside on the same logical device (otherwise, ERRNO will be set to `EXDEV'). Wildcards are not allowed in either OLDNAME or NEWNAME. DOS won't allow renaming a current directory even on a non-default drive (you will get the `EBUSY' or `EINVAL' in ERRNO). `ENAMETOOLONG' will be returned for pathnames which are longer than the limit imposed by DOS. If OLDNAME doesn't exist, ERRNO will be set to `ENOENT'. For most of the other calamities, DOS will usually set ERRNO to `EACCES'. If anything goes wrong during the operation of `rename()', the function tries very hard to leave the things as ther were before it was invoked, but it might not always succeed. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- ANSI, POSIX Example ------- rename("c:/mydir/some.doc", "c:/yourdir/some.sav"); rename("c:/path1/mydir", "c:/path2"); File: libc.info, Node: rewind, Next: rewinddir, Prev: rename, Up: Alphabetical List rewind ====== Syntax ------ #include <stdio.h> void rewind(FILE *file); Description ----------- This function repositions the file pointer to the beginning of the file and clears the error indicator. Return Value ------------ None. Portability ----------- ANSI, POSIX Example ------- rewind(stdin); File: libc.info, Node: rewinddir, Next: rindex, Prev: rewind, Up: Alphabetical List rewinddir ========= Syntax ------ #include <dirent.h> void rewinddir(DIR *dir); Description ----------- This function resets the position of the DIR so that the next call to `readdir' (*note readdir::.) starts at the beginning again. Return Value ------------ None. Portability ----------- not ANSI, POSIX Example ------- DIR *d = opendir("."); rewinddir(d); File: libc.info, Node: rindex, Next: rmdir, Prev: rewinddir, Up: Alphabetical List rindex ====== Syntax ------ #include <strings.h> char *rindex(const char *string, int ch); Description ----------- Returns a pointer to the last occurrence of CH in STRING. Note that the `NULL' character counts, so if you pass zero as CH you'll get a pointer to the end of the string back. Return Value ------------ A pointer to the character, or `NULL' if it wasn't found. Portability ----------- not ANSI, not POSIX Example ------- char *last_slash = rindex(filename, '/'); File: libc.info, Node: rmdir, Next: run_child, Prev: rindex, Up: Alphabetical List rmdir ===== Syntax ------ #include <unistd.h> int rmdir(const char *dirname); Description ----------- This function removes directory DIRNAME. The directory must be empty. Return Value ------------ Zero if the directory was removed, nonzero on failure. Portability ----------- not ANSI, POSIX Example ------- rmdir("/tmp/datadir"); File: libc.info, Node: run_child, Next: save_npx, Prev: rmdir, Up: Alphabetical List run_child ========= Syntax ------ #include <debug/dbgcom.h> void run_child (void); Description ----------- This function starts or resumes the debugged program, via a `longjmp' to the debuggee's code. When the debuggee hits a breakpoint, or exits normally, the exception handler that is called to service the breakpoint exception will `longjmp' back to `run_child', and it will then return to the caller. After `run_child' returns, the debugger usually examines the `a_tss' variable to find out the reason the debuggee stopped. The `a_tss' variable is defined by the header `debug/tss.h' as follows: typedef struct TSS { unsigned short tss_back_link; unsigned short res0; unsigned long tss_esp0; unsigned short tss_ss0; unsigned short res1; unsigned long tss_esp1; unsigned short tss_ss1; unsigned short res2; unsigned long tss_esp2; unsigned short tss_ss2; unsigned short res3; unsigned long tss_cr3; unsigned long tss_eip; unsigned long tss_eflags; unsigned long tss_eax; unsigned long tss_ecx; unsigned long tss_edx; unsigned long tss_ebx; unsigned long tss_esp; unsigned long tss_ebp; unsigned long tss_esi; unsigned long tss_edi; unsigned short tss_es; unsigned short res4; unsigned short tss_cs; unsigned short res5; unsigned short tss_ss; unsigned short res6; unsigned short tss_ds; unsigned short res7; unsigned short tss_fs; unsigned short res8; unsigned short tss_gs; unsigned short res9; unsigned short tss_ldt; unsigned short res10; unsigned short tss_trap; unsigned char tss_iomap; unsigned char tss_irqn; unsigned long tss_error; } TSS; extern TSS a_tss; See the example below for a typical tests after `run_child' returns. Note that, generally, you'd need to save the standard handles before calling `run_child' and restore them after it returns. Otherwise, if the debuggee redirects one of its standard handles, the corresponding debugger's standard handle is redirected as well. *Note redir_to_child::, and see *Note redir_to_debugger::. Portability ----------- not ANSI, not POSIX Example ------- save_npx (); run_child (); load_npx (); if (a_tss.tss_irqn == 0x21) { status = DEBUGGEE_EXITED; exit_code = a_tss.tss_eax & 0xff; } else { status = DEBUGGEE_GOT_SIGNAL if (a_tss.tss_irqn == 0x75) signal_number = SIGINT; else if (a_tss.tss_irqn == 1 || a_tss.tss_irqn == 3) signal_number = SIGTRAP; /* a breakpoint */ } File: libc.info, Node: save_npx, Next: sbrk, Prev: run_child, Up: Alphabetical List save_npx ======== Syntax ------ #include <debug/dbgcom.h> extern NPX npx; void save_npx (void); Description ----------- This function saves the state of the x87 numeric processor in the external variable `npx'. This variable is a structure defined as follows in the header `debug/dbgcom.h': typedef struct { unsigned short sig0; unsigned short sig1; unsigned short sig2; unsigned short sig3; unsigned short exponent:15; unsigned short sign:1; } NPXREG; typedef struct { unsigned long control; unsigned long status; unsigned long tag; unsigned long eip; unsigned long cs; unsigned long dataptr; unsigned long datasel; NPXREG reg[8]; long double st[8]; char st_valid[8]; long double mmx[8]; char in_mmx_mode; char top; } NPX; `save_npx' should be called immediately before `run_child' (*note run_child::.) is called to begin or resume the debugged program. To restore the x87 state when control is returned to the debugger, call `load_npx', see *Note load_npx::. Portability ----------- not ANSI, not POSIX Example ------- save_npx (); run_child (); load_npx (); File: libc.info, Node: sbrk, Next: scanf, Prev: save_npx, Up: Alphabetical List sbrk ==== Syntax ------ #include <unistd.h> void *sbrk(int delta) Description ----------- This function changes the "break" of the program by adding DELTA to it. This is the highest address that your program can access without causing a violation. Since the heap is the region under the break, you can expand the heap (where `malloc' gets memory from) by increasing the break. This function is normally accessed only by `malloc' (*note malloc::.). Return Value ------------ The address of the first byte outside of the previous valid address range, or -1 if no more memory could be accessed. In other words, a pointer to the chunk of heap you just allocated, if you had passed a positive number. Portability ----------- not ANSI, not POSIX Example ------- char *buf; buf = sbrk(1000); /* allocate space */ File: libc.info, Node: scanf, Next: Screen Variables, Prev: sbrk, Up: Alphabetical List scanf ===== Syntax ------ #include <stdio.h> int scanf(const char *format, ...); Description ----------- This function scans formatted text from `stdin' and stores it in the variables pointed to by the arguments. *Note scanf::. The format string contains regular characters which much match the input exactly as well as a conversion specifiers, which begin with a percent symbol. Any whitespace in the format string matches zero or more of any whitespace characters in the input. Thus, a single space may match a newline and two tabs in the input. All conversions except `c' and `[' also skip leading whitespace automatically. Each conversion specifier contains the following fields: * An asterisk (`*') which indicates that the input should be converted according to the conversion spec, but not stored anywhere. This allows to describe an input field that is to be skipped. * A width specifier, which specifies the maximum number of input characters to use in the conversion. * An optional conversion qualifier, which may be `h' to specify `short', `l' to specify doubles or long ints, or `L' or `ll' (two lower-case ell letters) to specify long doubles and the long long type. If the `h' qualifier appears before a specifier that implies conversion to a `long' or `float' or `double', like in `%hD' or `%hf', it is generally ignored. * The conversion type specifier: `c' Copy the next character (or WIDTH characters) to the given buffer. This conversion suppresses skipping of the leading whitespace; use `%1s' to read the next non-whitespace character. Unlike with `%s', the copied characters are *not* terminated with a null character. If the WIDTH parameter is not specified, a WIDTH of one is implied. `d' Convert the input to a signed `int' using 10 as the base of the number representation. `hd' Convert the input to a signed `short' using 10 as the base. `ld' `D' Convert the input to a signed `long' using 10 as the base. `Ld' `lld' `lD' Convert the input to a signed `long long' using 10 as the base. `e' `E' `f' `F' `g' `G' Convert the input to a floating point number (a `float'). `le' `lE' `lf' `lF' `lg' `lG' Convert the input to a `double'. `Le' `LE' `lle' `llE' `Lf' `LF' `llf' `llF' `Lg' `LG' `llg' `llG' Convert the input to a `long double'. `i' Convert the input, determining base automatically by the presence of `0x' or `0' prefixes, and store in an `int'. *Note strtol::. `hi' Like `i', but stores the result in a `short'. `li' `I' Like `i', but stores the result in a `long'. `Li' `lli' `lI' Like `i', but stores the result in a `long long'. `n' Store the number of characters scanned so far into the `int' pointed to by the argument. `hn' Like `n', but the argument should point to a `short'. `ln' Like `n', but the argument should point to a `long'. `Ln' `lln' Like `n', but the argument should point to a `long long'. `o' Convert the input to a signed `int', using base 8. `ho' Convert the input to a signed `short', using base 8. `lo' `O' Convert the input to a signed `long', using base 8. `Lo' `llo' `lO' Convert the input to a signed `long long', using base 8. `p' Convert the input to a pointer. This is like using the `x' format. `s' Copy the input to the given string, skipping leading whitespace and copying non-whitespace characters up to the next whitespace. The string stored is then terminated with a null character. `u' Convert the input to an unsigned `int' using 10 as the base. `hu' Convert the input to an unsigned `short' using 10 as the base. `lu' `U' Convert the input to an unsigned `long' using 10 as the base. `Lu' `llu' `lU' Convert the input to an unsigned `long long' using 10 as the base. `x' `X' Convert the input to an unsigned `int', using base 16. `hx' `hX' Convert the input to an unsigned `short', using base 16. `lx' `lX' Convert the input to an unsigned `long', using base 16. `Lx' `LX' `llx' `llX' Convert the input to an unsigned `long long', using base 16. `[...]' Stores the matched characters in a `char' array, followed by a terminating null character. If you do not specify the WIDTH parameter, `scanf' behaves as if WIDTH had a very large value. Up to WIDTH characters are consumed and assigned, provided that they match the specification inside the brackets. The characters between the brackets determine which characters are allowed, and thus when the copying stops. These characters may be regular characters (example: `[abcd]') or a range of characters (example: `[a-d]'). If the first character is a caret (`^'), then the set specifies the set of characters that do not get copied (i.e. the set is negated). To specify that the set contains a close-bracket (`]'), put it immediately after `[' or `[^'. To specify a literal dash (`-'), write it either immediately after `[' or `[^', or immediately before the closing `]'. `%' This must match a percent character in the input. Integer formats make use of `strtol' or `strtoul' to perform the actual conversions. Floating-point conversions use `strtod' and `_strtold'. Return Value ------------ The number of items successfully matched and assigned. If input ends, or if there is any input failure before the first item is converted and assigned, `EOF' is returned. Note that literal characters (including whitespace) in the format string which matched input characters count as "converted items", so input failure *after* such characters were read and matched will *not* cause `EOF' to be returned. Portability ----------- ANSI (see note 1), POSIX Notes: 1. The conversion specifiers `F', `D', `I', `O', and `U' are DJGPP extensions; they are provided for compatibility with Borland C and other compilers. The conversion specifiers for the `long long' data type are GCC extensions. The meaning of `[a-c]' as a range of characters is a very popular extension to ANSI (which merely says a dash "may have a special meaning" in that context). Example ------- int x, y; char buf[100]; scanf("%d %d %s", &x, &y, buf); /* read to end-of-line */ scanf("%d %[^\n]\n", &x, buf); /* read letters only */ scanf("[a-zA-Z]", buf); File: libc.info, Node: Screen Variables, Next: ScreenClear, Prev: scanf, Up: Alphabetical List Screen Variables ================ Syntax ------ #include <go32.h> #include <pc.h> unsigned long ScreenPrimary; unsigned long ScreenSecondary; extern unsigned char ScreenAttrib; Description ----------- The first two variables (actually, they are #define'd aliases to fields in the _GO32_INFO_BLOCK structure *note _go32_info_block::.) allow access to the video memory of the primary and secondary screens as if they were arrays. To reference them, you must use dosmemget()/dosmemput() functions (*Note dosmemget::, *Note dosmemput::) or any one of the far pointer functions (*note _far*::.), as the video memory is *not* mapped into your default address space. The variable ScreenAttrib holds the current attribute which is in use by the text screen writes. The attribute is constructed as follows: bits 0-3 - foreground color; bits 4-6 - background color; bit 7 - blink on (1) or off (0). Example ------- _farpokew(_dos_ds, ScreenPrimary, ( ((unsigned short) attr) << 8) + char )); File: libc.info, Node: ScreenClear, Next: ScreenCols, Prev: Screen Variables, Up: Alphabetical List ScreenClear =========== Syntax ------ #include <pc.h> void ScreenClear(void); Description ----------- This function clears the text screen. It overwrites it by blanks with the current background and foreground as specified by ScreenAttrib (*note Screen Variables::.). Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- ScreenClear(); File: libc.info, Node: ScreenCols, Next: ScreenGetChar, Prev: ScreenClear, Up: Alphabetical List ScreenCols ========== Syntax ------ #include <pc.h> int ScreenCols(void); Description ----------- This function returns the number of columns of the screen. It does so by looking at the byte at the absolute address 40:4Ah in the BIOS area. In text modes, the meaning of number of columns is obvious; in graphics modes, this value is the number of columns of text available when using the video BIOS functions to write text. Return Value ------------ The number of columns. Portability ----------- not ANSI, not POSIX Example ------- int available_columns = ScreenCols(); File: libc.info, Node: ScreenGetChar, Next: ScreenGetCursor, Prev: ScreenCols, Up: Alphabetical List ScreenGetChar ============= Syntax ------ #include <pc.h> void ScreenGetChar(int *ch, int *attr, int col, int row); Description ----------- This function stores the character and attribute of the current primary screen at row given by ROW and column given by COL (these are zero-based) into the integers whose address is specified by CH and ATTR. It does so by directly accessing the video memory, so it will only work when the screen is in text mode. You can pass the value `NULL' in each of the pointers if you do not want to retrieve the the corresponding information. *Warning:* note that both the variables CH and ATTR are pointers to an `int', not to a `char'! You *must* pass a pointer to an `int' there, or your program will crash or work erratically. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- int ch, attr; ScreenGetChar(&ch, &attr, 0, 0); File: libc.info, Node: ScreenGetCursor, Next: ScreenMode, Prev: ScreenGetChar, Up: Alphabetical List ScreenGetCursor =============== Syntax ------ #include <pc.h> void ScreenGetCursor(int *row, int *column); Description ----------- This function retrieves the current cursor position of the default video page by calling function 3 of the interrupt 10h, and stores it in the variables pointed by ROW and COLUMN. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- ScreenGetCursor(&wherex, &wherey); File: libc.info, Node: ScreenMode, Next: ScreenPutChar, Prev: ScreenGetCursor, Up: Alphabetical List ScreenMode ========== Syntax ------ #include <pc.h> int ScreenMode(void); Description ----------- This function reports the current video mode as known to the system BIOS. It does so by accessing the byte at absolute address 40:49h. Return Value ------------ The video mode. Portability ----------- not ANSI, not POSIX Example ------- video_mode = ScreenMode(); File: libc.info, Node: ScreenPutChar, Next: ScreenPutString, Prev: ScreenMode, Up: Alphabetical List ScreenPutChar ============= Syntax ------ #include <pc.h> void ScreenPutChar(int ch, int attr, int col, int row); Description ----------- This function writes the character whose value is specified in CH with an attribute ATTR at row given by ROW and column given by COL, which are zero-based. It does so by directly accessing the video memory, so it will only work when the screen is in text mode. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- ScreenPutChar('R', (BLUE << 4) | LIGHTMAGENTA, 75, 0); File: libc.info, Node: ScreenPutString, Next: ScreenRetrieve, Prev: ScreenPutChar, Up: Alphabetical List ScreenPutString =============== Syntax ------ #include <pc.h> void ScreenPutString(const char *str, int attr, int column, int row); Description ----------- Beginning at screen position given by COLUMN and ROW, this function displays the string given by STR. Each string character gets the attribute given by ATTR. If COLUMN or ROW have values outside legal range for current video mode, nothing happens. The variables ROW and COLUMN are zero-based (e.g., the topmost row is row 0). Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- ScreenPutString("Hello, world!", (BLUE << 4) | LIGHTBLUE, 20, 10); File: libc.info, Node: ScreenRetrieve, Next: ScreenRows, Prev: ScreenPutString, Up: Alphabetical List ScreenRetrieve ============== Syntax ------ #include <pc.h> void ScreenRetrieve(void *buf); Description ----------- This function stores a replica of the current primary screen contents in the buffer pointed to by BUF. It assumes without checking that BUF has enough storage to hold the data. The required storage can be computed as `ScreenRows()*ScreenCols()*2' (*Note ScreenRows::, *Note ScreenCols::). Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- unsigned *saved_screen = (unsigned *)alloca(ScreenRows()*ScreenCols()*2; ScreenRetrieve(saved_screen); File: libc.info, Node: ScreenRows, Next: ScreenSetCursor, Prev: ScreenRetrieve, Up: Alphabetical List ScreenRows ========== Syntax ------ #include <pc.h> int ScreenRows(void); Description ----------- This function returns the number of rows of the text screen. It does so by looking at the byte at the absolute address 40:84h in the BIOS area. This method works only for video adapters with their own BIOS extensions, like EGA, VGA, SVGA etc. Return Value ------------ The number of rows. Portability ----------- not ANSI, not POSIX Example ------- int rows = ScreenRows(); File: libc.info, Node: ScreenSetCursor, Next: ScreenUpdate, Prev: ScreenRows, Up: Alphabetical List ScreenSetCursor =============== Syntax ------ #include <pc.h> void ScreenSetCursor(int row, int column); Description ----------- This function moves the cursor position on the default video page to the point given by (zero-based) ROW and COLUMN, by calling function 2 of interrupt 10h. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- ScreenSetCursor(0, 0); /* home the cursor */ File: libc.info, Node: ScreenUpdate, Next: ScreenUpdateLine, Prev: ScreenSetCursor, Up: Alphabetical List ScreenUpdate ============ Syntax ------ #include <pc.h> void ScreenUpdate(void *buf); Description ----------- This function writes the contents of the buffer BUF to the primary screen. The buffer should contain an exact replica of the video memory, including the characters and their attributes. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- ScreenUpdate(saved_screen); File: libc.info, Node: ScreenUpdateLine, Next: ScreenVisualBell, Prev: ScreenUpdate, Up: Alphabetical List ScreenUpdateLine ================ Syntax ------ #include <pc.h> void ScreenUpdateLine(void *buf, int row); Description ----------- This function writes the contents of BUF to the screen line number given in ROW (the topmost line is row 0), on the primary screen. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- ScreenUpdateLine(line_buf, 10); File: libc.info, Node: ScreenVisualBell, Next: searchpath, Prev: ScreenUpdateLine, Up: Alphabetical List ScreenVisualBell ================ Syntax ------ #include <pc.h> void ScreenVisualBell(void); Description ----------- This function flashes the screen colors to produce the effect of "visual bell'. It does so by momentarily inverting the colors of every character on the screen. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- ScreenVisualBell(); File: libc.info, Node: searchpath, Next: seekdir, Prev: ScreenVisualBell, Up: Alphabetical List searchpath ========== Syntax ------ #include <dir.h> char * searchpath(const char *file); Description ----------- Given a name of a file in FILE, searches for that file in a list of directories, including the current working directory and directories listed in the `PATH' environment variable, and if found, returns the file name with leading directories prepended, so that the result can be used to access the file (e.g. by calling `open' or `stat'). If FILE includes a drive letter or leading directories, `searchpath' first tries that name unaltered, in case it is already a fully-qualified path, or is relative to the current working directory. If that fails, it tries every directory in `PATH' in turn. Note that this will find e.g. `c:/foo/bar/baz.exe' if you pass `bar/baz.exe' to `searchpath' and if `c:/foo' is mentioned in `PATH'. Return Value ------------ When successfull, the function returns a pointer to a static buffer where the full pathname of the found file is stored. Otherwise, it returns `NULL'. (The static buffer is overwritten on each call.) Portability ----------- not ANSI, not POSIX This function is provided for compatibility with Borland's library. However, note that the Borland version disregards the leading directories altogether and searches for the basename only. Thus, it will happily find e.g. `c:/foo/bar/baz.exe', even if the directory `c:/foo/bar' doesn't exist, provided that `baz.exe' is somewhere on your `PATH'. We think this is a bug, so DJGPP's implementation doesn't behave like that. Example ------- printf("%s was found as %s\n", argv[1], searchpath(argv[1])); File: libc.info, Node: seekdir, Next: select, Prev: searchpath, Up: Alphabetical List seekdir ======= Syntax ------ #include <dirent.h> void seekdir(DIR *dir, long loc); Description ----------- This function sets the location pointer in DIR to the specified LOC. Note that the value used for LOC should be either zero or a value returned by `telldir' (*note telldir::.). The next call to `readdir' (*note readdir::.) will read whatever entry follows that point in the directory. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- int q = telldir(dir); do_stuff(); seekdir(dir, q); File: libc.info, Node: select, Next: _set_screen_lines, Prev: seekdir, Up: Alphabetical List select ====== Syntax ------ #include <time.h> int select(int nfds, fd_set *readfds, fd_set *writefds, fd_set *exceptfds, struct timeval *timeout) Description ----------- This function waits for files to be ready for input or output, or to have exceptional condition pending, or for a timeout. Each `fd_set' variable is a bitmap representation of a set of file descriptors, one bit for every descriptor. The following macros shall be used to deal with these sets: `FD_ZERO(p)' Initialize the set to all zeros. `FD_SET(n, p)' Set member N in set P. `FD_CLR(n, p)' Clear member N in set P. `FD_ISSET(n, p)' Return the value of member N in set P. `FD_SETSIZE' The maximum number of descriptors supported by the system. The NFDS parameter is the number of bits to be examined in each of the `fd_set' sets: the function will only check file descriptors `0' through `NFDS - 1', even if some bits are set for descriptors beyond that. On input, some of the bits of each one of the `fd_set' sets for which the function should wait, should be set using the `FD_SET' macro. `select' examines only those descriptors whose bits are set. Any of `readfds', `writefds', and `exceptfds' can be a `NULL' pointer, if the caller is not interested in testing the corresponding conditions. On output, if `select' returns a non-negative value, each non-`NULL' argument of the three sets will be replaced with a subset in which a bit is set for every descriptor that was found to be, respectively, ready for input, ready for output, and pending an exceptional condition. Note that if `select' returns -1, meaning a failure, the descriptor sets are *unchanged*, so you should always test the return value before looking at the bits in the returned sets. The TIMEOUT value may be a NULL pointer (no timeout, i.e., wait forever), a pointer to a zero-value structure (poll mode, i.e., test once and exit immediately), or a pointer to a `struct timeval' variable (timeout: `select' will repeatedly test all the descriptors until some of them become ready, or the timeout expires). `struct timeval' is defined as follows: struct timeval { time_t tv_sec; long tv_usec; }; Return Value ------------ On successfull return, `select' returns the number of files ready, or 0, if the timeout expired. The input sets are replaced with subsets that describe which files are ready for which operations. If `select' returns 0 (i.e., the timeout has expired), all the non-`NULL' sets have all their bits reset to zero. On failure, `select' returns -1, sets `errno' to a suitable value, and leaves the descriptor sets unchanged. Portability ----------- not ANSI, not POSIX Example ------- struct timeval timeout; fd_set read_fds, write_fds; int i, select_result; timeout.tv_sec = 5; /* 5-second timeout */ timeout.tv_usec = 0; /* Display status of the 5 files open by default. */ for (i = 0; i < 5; i++) { FD_ZERO (&read_fds); FD_SET (i, &read_fds); select_result = select (i + 1, &read_fds, 0, 0, &timeout); if (select_result == -1) { fprintf(stderr, "%d: Failure for input", i); perror(""); } else fprintf(stderr, "%d: %s ready for input\n", i, select_result ? "" : "NOT"); FD_ZERO (&write_fds); FD_SET (i, &write_fds); select_result = select (i + 1, 0, &write_fds, 0, &timeout); if (select_result == -1) { fprintf(stderr, "%d: Failure for output", i); perror(""); } else fprintf(stderr, "%d: %s ready for output\n", i, select_result ? "" : "NOT"); } Implementation Notes -------------------- The following notes describe some details pertinent to the DJGPP implementation of `select': * While `select' waits for the timeout to expire, it repeatedly calls the `__dpmi_yield' function (*note __dpmi_yield::.), so that any other programs that run at the same time (e.g., on Windows) get more CPU time. * A file handle that belongs to a `FILE' object created by `fopen' or `fdopen' (*note fopen::.) for which `feof' or `ferror' return non-zero, will be reported in the `exceptfds' set; also, such a handle will be reported not input-ready if there are no pending buffered characters in the `FILE' object. This might be a feature or a bug, depending on your point of view; in particular, Unix implementations usually don't check buffered input. Portable programs should refrain from mixing `select' with buffered I/O. * DOS doesn't support exceptional conditions, so file handles used for unbuffered I/O will *never* be marked in `exceptfds'. * DOS always returns an output-ready indication for a file descriptor connected to a disk file. So use of `writefds' is only meaningful for character devices. * The usual text-mode input from the keyboard and other character devices is line-buffered by DOS. This means that if you type one character, `select' will indicate that file handle 0 is ready for input, but a call to `getc' will still block until the <Enter> key is pressed. If you need to make sure that reading a single character won't block, you should read either with BIOS functions such as `getkey' (*note getkey::., or with raw input DOS functions such as `getch' (*note getch::.), or switch the handle to binary mode with a call to `setmode' (*note setmode::.). File: libc.info, Node: _set_screen_lines, Next: setbuf, Prev: select, Up: Alphabetical List _set_screen_lines ================= Syntax ------ #include <conio.h> void _set_screen_lines(int nlines); Description ----------- This function sets the text screen width to 80 and its height to the value given by NLINES, which can be one of the following: 25, 28, 35, 40, 43 or 50. On a CGA, only 25-line screen is supported. On an EGA, you can use 25, 35 and 43. VGA, PGA and MCGA support all of the possible dimensions. The number of columns (i.e., screen width) is 80 for all of the above resolutions, because the standard EGA/VGA has no way of changing it. After this function returns, calls to `gettextinfo()' will return the actual screen dimensions as set by `_set_screen_lines()'. That is, you can e.g. test whether `_set_screen_lines()' succeeded by checking the screen height returned by `gettextinfo()' against the desired height. This function has a side effect of erasing the screen contents, so application programs which use it should make their own arrangements to redisplay it. Portability ----------- not ANSI, not POSIX File: libc.info, Node: setbuf, Next: setbuffer, Prev: _set_screen_lines, Up: Alphabetical List setbuf ====== Syntax ------ #include <stdio.h> void setbuf(FILE *file, char *buffer); Description ----------- This function modifies the buffering characteristics of FILE. First, if the file already has a buffer, it is freed. If there was any pending data in it, it is lost, so this function should only be used immediately after a call to `fopen'. If the BUFFER passed is `NULL', the file is set to unbuffered. If a non-`NULL' buffer is passed, it must be at least `BUFSIZ' bytes in size, and the file is set to fully buffered. *Note setbuffer::. *Note setlinebuf::. *Note setvbuf::. Return Value ------------ None. Portability ----------- ANSI, POSIX Example ------- setbuf(stdout, malloc(BUFSIZ)); File: libc.info, Node: setbuffer, Next: setcbrk, Prev: setbuf, Up: Alphabetical List setbuffer ========= Syntax ------ #include <stdio.h> void setbuffer(FILE *file, char *buffer, int length); Description ----------- This function modifies the buffering characteristics of FILE. First, if the file already has a buffer, it is freed. If there was any pending data in it, it is lost, so this function should only be used immediately after a call to `fopen'. If the BUFFER passed is `NULL', the file is set to unbuffered. If a non-`NULL' buffer is passed, it must be at least SIZE bytes in size, and the file is set to fully buffered. *Note setbuf::. *Note setlinebuf::. *Note setvbuf::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- setbuffer(stdout, malloc(10000), 10000); File: libc.info, Node: setcbrk, Next: _setcursortype, Prev: setbuffer, Up: Alphabetical List setcbrk ======= Syntax ------ #include <dos.h> void setcbrk(int check); Description ----------- Set the setting of the Ctrl-Break checking flag in MS-DOS. If CHECK is zero, checking is not done. If nonzero, checking is done. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _setcursortype, Next: setdate, Prev: setcbrk, Up: Alphabetical List _setcursortype ============== Syntax ------ #include <conio.h> void _setcursortype(int _type); Description ----------- Sets the cursor type. _TYPE is one of the following: `_NOCURSOR' No cursor is displayed. `_SOLIDCURSOR' A solid block is displayed. `_NORMALCURSOR' An underline cursor is displayed. Portability ----------- not ANSI, not POSIX File: libc.info, Node: setdate, Next: setdisk, Prev: _setcursortype, Up: Alphabetical List setdate ======= Syntax ------ #include <dos.h> void setdate(struct date *ptr); Description ----------- This function sets the current time. For the description of `struct date', see *Note getdate::. Also see *Note settime::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- struct date d; setdate(&d); File: libc.info, Node: setdisk, Next: setenv, Prev: setdate, Up: Alphabetical List setdisk ======= Syntax ------ #include <dir.h> int setdisk(int drive); Description ----------- This function sets the current disk (0=A). See also *Note getdisk::. Return Value ------------ The highest drive actually present that the system can reference. Portability ----------- not ANSI, not POSIX Example ------- printf("There are %d drives\n", setdisk(getdisk())); File: libc.info, Node: setenv, Next: setftime, Prev: setdisk, Up: Alphabetical List setenv ====== Syntax ------ #include <stdlib.h> int setenv(const char *name, const char *value, int rewrite); Description ----------- This function sets the environment variable NAME to VALUE. If REWRITE is set, then this function will replace any existing value. If it is not set, it will only put the variable into the environment if that variable isn't already defined. Return Value ------------ Zero on success, -1 on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: setftime, Next: setgid, Prev: setenv, Up: Alphabetical List setftime ======== Syntax ------ #include <dos.h> int setftime(int handle, struct ftime *ftimep); Description ----------- This function sets the modification time of a file. Note that since writing to a file, and closing a file opened for writing, also sets the modification time, you should only use this function on files opened for reading. *Note getftime::, for the description of `struct ftime'. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- int q = open("data.txt", O_RDONLY); struct ftime f; f.ft_sec = f.ft_min = f.ft_hour = f.ft_day = f.ft_month = f.ft_year = 0; setftime(q, &f); close(q); File: libc.info, Node: setgid, Next: setgrent, Prev: setftime, Up: Alphabetical List setgid ====== Syntax ------ #include <unistd.h> int setgid(gid_t gid); Description ----------- This function is simulated, since MS-DOS does not support group IDs. Return Value ------------ If GID is equal to that returned by *note getgid::., returns zero. Otherwise, returns -1 and sets `errno' to EPERM. Portability ----------- not ANSI, POSIX File: libc.info, Node: setgrent, Next: setitimer, Prev: setgid, Up: Alphabetical List setgrent ======== Syntax ------ #include <grp.h> void setgrent(void); Description ----------- This function should be called before any call to `getgrent', `getgrgid', or `getgrnam', to start searching the groups' list from the beginning. *Note getgrent::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: setitimer, Next: setjmp, Prev: setgrent, Up: Alphabetical List setitimer ========= Syntax ------ #include <sys/time.h> extern long __djgpp_clock_tick_interval; struct timeval { time_t tv_sec; long tv_usec; }; struct itimerval { struct timeval it_interval; /* timer interval */ struct timeval it_value; /* current value */ }; int setitimer(int which, struct itimerval *value, struct itimerval *ovalue); Description ----------- Each process has two interval timers, `ITIMER_REAL' and `ITIMER_PROF', which raise the signals `SIGALRM' and `SIGPROF', respectively. These are typically used to provide `alarm' and profiling capabilities. This function changes the current value of the interval timer specified by WHICH to the values in structure VALUE. The previous value of the timer is returned in OVALUE if it is not a `NULL' pointer. When the timer expires, the appropriate signal is raised. If VALUE is a `NULL' pointer, `setitimer' stores the previous timer value in OVALUE (if it is non-`NULL'), like `getitimer' does, but otherwise does nothing. A timer is defined by the `itimerval' structure. If the `it_value' member is non-zero it specifies the time to the next timer expiration. If `it_interval' is non-zero, it specifies the value with which to reload the timer upon expiration. Setting `it_value' to zero disables a timer. Setting `it_interval' to zero causes the timer to stop after the next expiration (assuming that `it_value' is non-zero). Although times can be given with microsecond resolution, the granularity is determined by the timer interrupt frequency. Time values smaller than the system clock granularity will be rounded up to that granularity, before they are used. This means that passing a very small but non-zero value in `value->it_interval.tv_usec' will cause the system clock granularity to be stored and returned by the next call to `getitimer'. See the example below. If an application changes the system clock speed by reprogramming the timer chip, it should make the new clock speed known to `setitimer', otherwise intervals smaller than the default PC clock speed cannot be set with a call to `setitimer' due to rounding up to clock granularity. To this end, an external variable `__djgpp_clock_tick_interval' is provided, which should be set to the number of microseconds between two timer ticks that trigger Interrupt 8. The default value of this variable is `-1', which causes `setitimer' to work with 54926 microsecond granularity that corresponds to the standard 18.2Hz clock frequency. The library never changes the value of `__djgpp_clock_tick_interval'. Return Value ------------ Returns 0 on success, -1 on failure (and sets `errno'). Portability ----------- not ANSI, not POSIX Bugs ---- This version uses `uclock' (*note uclock::.) to determine the time of expiration. Under Windows 3.X, this fails because the OS reprograms the timer. Under Windows 9X, `uclock' sometimes reports erratic (non-increasing) time values; in these cases the timer might fire at a wrong time. A misfeature of Windows 9X prevents the timer tick interrupt from being delivered to programs that are in the background (i.e. don't have the focus), even though the program itself might continue to run, if you uncheck the `Background: Always suspend' property in the Property Sheets. Therefore, the timers will not work in background programs on Windows 9X. Also, debuggers compiled with DJGPP v2.02 and earlier cannot cope with timers and report `SIGSEGV' or `SIGABRT', since signals were not supported in a debugged program before DJGPP v2.03. Example ------- /* Find out what is the system clock granularity. */ struct itimerval tv; tv.it_interval.tv_sec = 0; tv.it_interval.tv_usec = 1; tv.it_value.tv_sec = 0; tv.it_value.tv_usec = 0; setitimer (ITIMER_REAL, &tv, 0); setitimer (ITIMER_REAL, 0, &tv); printf ("System clock granularity: %ld microseconds.\n", tv.it_interval.tv_usec); File: libc.info, Node: setjmp, Next: setlinebuf, Prev: setitimer, Up: Alphabetical List setjmp ====== Syntax ------ #include <setjmp.h> int setjmp(jmp_buf j); Description ----------- This function stores the complete CPU state into J. This information is complete enough that `longjmp' (*note longjmp::.) can return the program to that state. It is also complete enough to implement coroutines. Return Value ------------ This function will return zero if it is returning from it's own call. If longjmp is used to restore the state, it will return whatever value was passed to longjmp, except if zero is passed to longjmp it will return one. Portability ----------- ANSI, POSIX Example ------- jmp_buf j; if (setjmp(j)) return; do_something(); longjmp(j, 1); File: libc.info, Node: setlinebuf, Next: setlocale, Prev: setjmp, Up: Alphabetical List setlinebuf ========== Syntax ------ #include <stdio.h> void setlinebuf(FILE *file); Description ----------- This function modifies the buffering characteristics of FILE. First, if the file already has a buffer, it is freed. If there was any pending data in it, it is lost, so this function should only be used immediately after a call to `fopen'. Next, a buffer is allocated and the file is set to line buffering. *Note setbuf::. *Note setlinebuf::. *Note setvbuf::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- setlinebuf(stderr); File: libc.info, Node: setlocale, Next: setmntent, Prev: setlinebuf, Up: Alphabetical List setlocale ========= Syntax ------ #include <locale.h> char *setlocale(int category, const char *locale); Description ----------- This function sets part or all of the current locale. The CATEGORY is one of the following: `LC_ALL' Set all parts of the locale. `LC_COLLATE' Set the collating information. `LC_CTYPE' Set the character type information. `LC_MONETARY' Set the monetary formatting information. `LC_NUMERIC' Set the numeric formatting information. `LC_TIME' Set the time formatting information. The LOCALE should be the name of the current locale. Currently, only the "C" and "POSIX" locales are supported. If the LOCALE is NULL, no action is performed. If LOCALE is "", the locale is identified by environment variables (currently not supported). *Note localeconv::. Return Value ------------ A static string naming the current locale for the given category, or NULL if the requested locale is not supported. Portability ----------- ANSI, POSIX Example ------- setlocale(LC_ALL, "C"); File: libc.info, Node: setmntent, Next: setmode, Prev: setlocale, Up: Alphabetical List setmntent ========= Syntax ------ #include <mntent.h> FILE *setmntent(char *filename, const char *mode); Description ----------- This function returns an open FILE* pointer which can be used by getmntent (*note getmntent::.). The arguments FILENAME and MODE are always ignored under MS-DOS, but for portability should be set, accordingly, to the name of the file which describes the mounted filesystems and the open mode of that file (like the MODE argument to `fopen', *note fopen::.). (There is no single standard for the name of the file that keeps the mounted filesystems, but it is usually, although not always, listed in the header `<mntent.h>'.) Return Value ------------ The `FILE*' pointer is returned. For MS-DOS, this `FILE*' is not a real pointer and may only be used by `getmntent'. Portability ----------- not ANSI, not POSIX Example ------- #include <mntent.h> #if defined(MNT_MNTTAB) #define MNTTAB_FILE MNT_MNTTAB #elif defined(MNTTABNAME) #define MNTTAB_FILE MNTTABNAME #else #define MNTTAB_FILE "/etc/mnttab" #endif FILE *mnt_fp = setmntent (MNTTAB_FILE, "r"); File: libc.info, Node: setmode, Next: setpgid, Prev: setmntent, Up: Alphabetical List setmode ======= Syntax ------ #include <io.h> int setmode(int file, int mode); Description ----------- This function sets the mode of the given FILE to MODE, which is either `O_TEXT' or `O_BINARY'. It will also set the file into either cooked or raw mode accordingly, and set any `FILE*' objects that use this file into text or binary mode. When called to put FILE that refers to the console into binary mode, `setmode' will disable the generation of the signals `SIGINT' and `SIGQUIT' when you press, respectively, `Ctrl-<C>' and `Ctrl-<\>' (`Ctrl-<BREAK>' will still cause `SIGINT'), because many programs that use binary reads from the console will also want to get the `^C' and `^\' keys. You can use the `__djgpp_set_ctrl_c' library function (*note __djgpp_set_ctrl_c::.) if you want `Ctrl-<C>' and `Ctrl-<\>' to generate signals while console is read in binary mode. Note that, for buffered streams (`FILE*'), you must call `fflush' (*note fflush::.) before `setmode', or call `setmode' before writing anything to the file, for proper operation. Return Value ------------ When successful, the function will return the previous mode of the given FILE. In case of failure, -1 is returned and ERRNO is set. Portability ----------- not ANSI, not POSIX Example ------- setmode(0, O_BINARY); File: libc.info, Node: setpgid, Next: setpwent, Prev: setmode, Up: Alphabetical List setpgid ======= Syntax ------ #include <unistd.h> int setpgid(pid_t _pid, pid_t _pgid); Return Value ------------ -1 (EPERM) if _pgid is not your current pid, else zero. Portability ----------- not ANSI, POSIX File: libc.info, Node: setpwent, Next: setrlimit, Prev: setpgid, Up: Alphabetical List setpwent ======== Syntax ------ #include <pwd.h> void setpwent(void); Description ----------- This function reinitializes `getpwent' so that scanning will start from the start of the list. *Note getpwent::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: setrlimit, Next: setsid, Prev: setpwent, Up: Alphabetical List setrlimit ========= Syntax ------ #include <sys/resource.h> int setrlimit (int rltype, const struct rlimit *rlimitp); Description ----------- This function sets new limit pointed to by RLIMITP on the resource limit specified by RLTYPE. Note that currently it always fails. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX File: libc.info, Node: setsid, Next: setstate, Prev: setrlimit, Up: Alphabetical List setsid ====== Syntax ------ #include <unistd.h> pid_t setsid(void); Description ----------- This function does not do anything. It exists to assist porting from Unix. Return Value ------------ Return value of *note getpid::.. Portability ----------- not ANSI, POSIX File: libc.info, Node: setstate, Next: settime, Prev: setsid, Up: Alphabetical List setstate ======== Syntax ------ #include <stdlib.h> char *setstate(char *arg_state); Description ----------- Restores the random number generator (*note random::.) state from pointer ARG_STATE to state array. Return Value ------------ Pointer to old state information. Portability ----------- not ANSI, not POSIX File: libc.info, Node: settime, Next: settimeofday, Prev: setstate, Up: Alphabetical List settime ======= Syntax ------ #include <dos.h> void settime(struct time *ptr); Description ----------- This function sets the current time. For the description of `struct time', see *Note gettime::. Also see *Note setdate::. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- struct time t; settime(&t); File: libc.info, Node: settimeofday, Next: setuid, Prev: settime, Up: Alphabetical List settimeofday ============ Syntax ------ #include <time.h> int settimeofday(struct timeval *tp, ...); Description ----------- Sets the current GMT time. For compatibility, a second argument is accepted. *Note gettimeofday::, for information on the structure types. Return Value ------------ Zero if the time was set, nonzero on error. Portability ----------- not ANSI, not POSIX File: libc.info, Node: setuid, Next: setvbuf, Prev: settimeofday, Up: Alphabetical List setuid ====== Syntax ------ #include <unistd.h> int setuid(uid_t uid); Description ----------- This function is simulated, since MS-DOS does not support user IDs. Return Value ------------ If UID is equal to that returned by *note getuid::., returns zero. Otherwise, returns -1 and sets `errno' to EPERM. Portability ----------- not ANSI, POSIX File: libc.info, Node: setvbuf, Next: sigaction, Prev: setuid, Up: Alphabetical List setvbuf ======= Syntax ------ #include <stdio.h> int setvbuf(FILE *file, char *buffer, int type, int length); Description ----------- This function modifies the buffering characteristics of FILE. First, if the file already has a buffer, it is freed. If there was any pending data in it, it is lost, so this function should only be used immediately after a call to `fopen'. If the TYPE is `_IONBF', the BUFFER and LENGTH are ignored and the file is set to unbuffered mode. If the TYPE is `_IOLBF' or `_IOFBF', then the file is set to line or fully buffered, respectively. If BUFFER is `NULL', a buffer of size SIZE is created and used as the buffer. If BUFFER is non-`NULL', it must point to a buffer of at least size SIZE and will be used as the buffer. *Note setbuf::. *Note setbuffer::. *Note setlinebuf::. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- ANSI, POSIX Example ------- setvbuf(stderr, NULL, _IOLBF, 1000); File: libc.info, Node: sigaction, Next: sigaddset, Prev: setvbuf, Up: Alphabetical List sigaction ========= Syntax ------ #include <signal.h> int sigaction (int sig, const struct sigaction *act, struct sigaction *oact); Description ----------- This function allows to examine and/or change the action associated with a signal SIG. The `struct sigaction' structure, defined by the header file `signal.h', is declared as follows: struct sigaction { int sa_flags; /* flags for the action; currently ignored */ void (*sa_handler)(int); /* the handler for the signal */ sigset_t sa_mask; /* additional signals to be blocked */ }; The `sa_handler' member is a signal handler, see *Note signal::. The `sa_mask' member defines the signals, in addition to SIG, which are to be blocked during the execution of `sa_handler'. The `sigaction' function sets the structure pointed to by `oact' to the current action for the signal SIG, and then sets the new action for SIG as specified by ACT. If the ACT argument is `NULL', `sigaction' returns the current signal action in OACT, but doesn't change it. If the OACT argument is a `NULL' pointer, it is ignored. Thus, passing `NULL' pointers for both `act' and `oact' is a way to see if SIG is a valid signal number on this system (if not, `sigaction' will return -1 and set `errno'). Return Value ------------ 0 on success, -1 for illegal value of SIG. Portability ----------- not ANSI, POSIX File: libc.info, Node: sigaddset, Next: sigdelset, Prev: sigaction, Up: Alphabetical List sigaddset ========= Syntax ------ #include <signal.h> int sigaddset (sigset_t *set, int signo) Description ----------- This function adds the individual signal specified by SIGNO the set of signals pointed to by SET. Return Value ------------ 0 upon success, -1 if SET is a NULL pointer, or if SIGNO is specifies an unknown signal. Portability ----------- not ANSI, POSIX File: libc.info, Node: sigdelset, Next: sigemptyset, Prev: sigaddset, Up: Alphabetical List sigdelset ========= Syntax ------ #include <signal.h> int sigdelset (sigset_t *set, int signo) Description ----------- This function removess the individual signal specified by SIGNO from the set of signals pointed to by SET. Return Value ------------ 0 upon success, -1 if SET is a NULL pointer, or if SIGNO is specifies an unknown signal. Portability ----------- not ANSI, POSIX File: libc.info, Node: sigemptyset, Next: sigfillset, Prev: sigdelset, Up: Alphabetical List sigemptyset =========== Syntax ------ #include <signal.h> int sigemptyset (sigset_t *set) Description ----------- This function initializes the set of signals pointed to by SET to exclude all signals known to the DJGPP runtime system. Such an empty set, if passed to `sigprocmask' (*note sigprocmask::.), will cause all signals to be passed immediately to their handlers. Return Value ------------ 0 upon success, -1 if SET is a NULL pointer. Portability ----------- not ANSI, POSIX File: libc.info, Node: sigfillset, Next: sigismember, Prev: sigemptyset, Up: Alphabetical List sigfillset ========== Syntax ------ #include <signal.h> int sigfillset (sigset_t *set) Description ----------- This function initializes the set of signals pointed to by SET to include all signals known to the DJGPP runtime system. Such a full set, if set by `sigprocmask' (*note sigprocmask::.), will cause all signals to be blocked from delivery to their handlers. Note that the set returned by this function only includes signals in the range `SIGABRT..SIGTRAP'; software interrupts and/or user-defined signals aren't included. Return Value ------------ 0 upon success, -1 if SET is a NULL pointer. Portability ----------- not ANSI, POSIX Example ------- sigset_t full_set, prev_set; sigfillset (&full_set); sigprocmask (SIG_UNBLOCK, &full_set, &prev_set); File: libc.info, Node: sigismember, Next: siglongjmp, Prev: sigfillset, Up: Alphabetical List sigismember =========== Syntax ------ #include <signal.h> int sigismember (sigset_t *set, int signo) Description ----------- This function checks whether the signal specified by SIGNO is a member of the set of signals pointed to by SET. Return Value ------------ 1 if the specified signal is a member of the set, 0 if it isn't, or if SIGNO specifies an unknown signal, -1 if SET is a NULL pointer. Portability ----------- not ANSI, POSIX File: libc.info, Node: siglongjmp, Next: signal, Prev: sigismember, Up: Alphabetical List siglongjmp ========== Syntax ------ #include <setjmp.h> int siglongjmp(sigjmp_buf env, int val); Description ----------- *Note longjmp::. Portability ----------- not ANSI, POSIX File: libc.info, Node: signal, Next: sigpending, Prev: siglongjmp, Up: Alphabetical List signal ====== Syntax ------ #include <signal.h> void (*signal(int sig, void (*func)(int)))(int); Description ----------- Signals are generated in response to some exceptional behavior of the program, such as division by 0. A signal can also report some asynchronous event outside the program, such as someone pressing a `Ctrl-<BREAK>' key combination. Signals are numbered 0..255 for software interrupts and 256..287 for exceptions (exception number plus 256); other implementation-specific codes are specified in `<signal.h>' (see below). Every signal is given a mnemonic which you should use for portable programs. By default, signal `SIGQUIT' is discarded. This is so programs ported from other DOS environments, where `SIGQUIT' is generally not supported, continue to work as they originally did. If you want `SIGQUIT' to abort with a traceback, install `__djgpp_traceback_exit' as its handler (*note __djgpp_traceback_exit::.). The default handling for the rest of the signals is to print a traceback (a stack dump which describes the sequence of function calls leading to the generation of the signal) and abort the program by calling `_exit' (*note _exit::.). As an exception, the default handler for the signal `SIGINT' doesn't print the traceback, and calls `exit' instead of `_exit', when the INTR key (`Ctrl-C' by default) is pressed, so that programs could be shut down safely in this manner. `SIGINT' raised by `Ctrl-<BREAK>' does generate the traceback. The function `signal' allows you to change the default behavior for a specific signal. It registers FUNC as a signal handler for signal number SIG. After you register your function as the handler for a particular signal, it will be called when that signal occurs. The execution of the program will be suspended until the handler returns or calls `longjmp' (*note longjmp::.). You may pass `SIG_DFL' as the value of FUNC to reset the signal handling for the signal SIG to default (also *Note __djgpp_exception_toggle::, for a quick way to restore all the signals' handling to default), `SIG_ERR' to force an error when that signal happens, or `SIG_IGN' to ignore that signal. Signal handlers that you write are regular C functions, and may call any function that the ANSI/POSIX specs say are valid for signal handlers. For maximum portability, a handler for hardware interrupts and processor exceptions should only make calls to `signal', assign values to data objects of type `volatile sig_atomic_t' (defined as `int' on `<signal.h>') and return. Handlers for hardware interrupts need also be locked in memory (so that the operation of virtual memory mechanism won't swap them out), *Note locking memory regions: __dpmi_lock_linear_region. Handlers for software interrupts can also terminate by calling `abort', `exit' or `longjmp'. The following signals are defined on `<signal.h>': `SIGABRT' The Abort signal. Currently only used by the `assert' macro to terminate the program when an assertion fails (*note assert::.), and by the `abort' function (*note abort::.). `SIGFPE' The Floating Point Error signal. Generated in case of divide by zero exception (Int 00h), overflow exception (Int 04h), and any x87 co-processor exception, either generated by the CPU (Int 10h), or by the co-processor itself (Int 75h). The co-processor status word is printed by the default handler for this signal. *Note _status87::, for the definition of the individual bits of the status word. The DJGPP startup code masks all numeric exceptions, so this signal is usually only triggered by an integer divide by zero operation. If you want to unmask some of the numeric exceptions, see *Note _control87::. `SIGILL' The Invalid Execution signal. Currently only generated for unknown/invalid exceptions. `SIGINT' The Interrupt signal. Generated when an INTR key (`Ctrl-C' by default) or `Ctrl-<BREAK>' (Int 1Bh) key is hit. Note that when you open the console in binary mode, or switch it to binary mode by a call to `setmode' (*note setmode::.), generation of `SIGINT' as result of `Ctrl-C' key is disabled. This is so for programs (such as Emacs) which want to be able to read the `^C' character as any other character. Use the library function `__djgpp_set_ctrl_c' to restore `SIGINT' generation when `Ctrl-C' is hit, if you need this. *Note __djgpp_set_ctrl_c::, for details on how this should be done. `Ctrl-<BREAK>' always generates `SIGINT'. DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to generate `SIGINT' in response to the INTR key; you should be aware of this when you install a handler for the keyboard interrupt. Note that the key which generates `SIGINT' can be changed with a call to `__djgpp_set_sigint_key' function. *Note __djgpp_set_sigint_key::. `SIGSEGV' The invalid storage access (Segmentation Violation) signal. Generated in response to any of the following exceptions: Bound range exceeded in BOUND instruction (Int 05h), Double Exception or an exception in the exception handler (Int 08h), Segment Boundary violation by co-processor (Int 09h), Invalid TSS (Int 0Ah), Segment Not Present (Int 0Bh), Stack Fault (Int 0Ch), General Protection Violation (Int 0Dh), or Page Fault (Int 0Eh). Note that Int 09h is only generated on 80386 processor; i486 and later CPUs cause Int 0Dh when the co-processor accesses memory out of bounds. The Double Exception, Invalid TSS, Segment Not Present, Stack Fault, GPF, and Page Fault exceptions will cause an error code to be printed, if it is non-zero. `SIGTERM' The Termination Request signal. Currently unused. The signals below this are not defined by ANSI C, and cannot be used when compiling under `-ansi' option to `gcc'. `SIGALRM' The Alarm signal. Generated after certain time period has passed after a call to `alarm' library function (*note alarm::.). `SIGHUP' The Hang-up signal. Currently unused. `SIGKILL' The Kill signal. Currently unused. `SIGPIPE' The Broken Pipe signal. Currently unused. `SIGQUIT' The Quit signal. Generated when the QUIT key (`Ctrl-\' by default) is hit. The key that raises the signal can be changed with a call to `__djgpp_set_sigquit_key' function. *Note __djgpp_set_sigquit_key::. By default, `SIGQUIT' is discarded, even if its handler is `SIG_DFL', so that DOS programs which don't expect it do not break. You can change the effect of `SIGQUIT' to abort with traceback by installing `__djgpp_traceback_exit' as its handler. *Note __djgpp_traceback_exit::. DJGPP hooks the keyboard hardware interrupt (Int 09h) to be able to generate `SIGQUIT' in response to the QUIT key; you should be aware of this when you install a handler for the keyboard interrupt. `SIGUSR1' User-defined signal no. 1. `SIGUSR2' User-defined signal no. 2. The signals below are not defined by ANSI C and POSIX, and cannot be used when compiling under either `-ansi' or `-posix' options to `gcc'. `SIGTRAP' The Trap Instruction signal. Generated in response to the Debugger Exception (Int 01h) or Breakpoint Exception (Int 03h). `SIGNOFP' The No Co-processor signal. Generated if a co-processor (floating-point) instruction is encountered when no co-processor is installed (Int 07h). `SIGTIMR' The Timer signal. Used by the `setitimer' and `alarm' functions (*Note setitimer::, and *note alarm::.). `SIGPROF' The Profiler signal. Used by the execution profile gathering code in a program compiled with `-pg' option to `gcc'. Return Value ------------ The previous handler for signal SIG, or `SIG_ERR' if the value of SIG is outside legal limits. Signal Mechanism Implementation Notes ------------------------------------- Due to subtle aspects of protected-mode programs operation under MS-DOS, signal handlers cannot be safely called from hardware interrupt handlers. Therefore, DJGPP exception-handling mechanism arranges for the signal handler to be called on the first occasion that the program is in protected mode and touches any of its data. This means that if the exception occurs while the processor is in real mode, like when your program calls some DOS service, the signal handler won't be called until that call returns. For instance, if you call `read' (or `scanf', or `gets') to read text from the console and press `Ctrl-C', you will have to press `Enter' to terminate the `read' call to cause the signal handler for `SIGINT' to be called. Another significant implication of this implementation is that when the program isn't touching any of its data (like in very tight loops which only use values in the registers), it cannot be interrupted. Portability ----------- ANSI, POSIX File: libc.info, Node: sigpending, Next: sigprocmask, Prev: signal, Up: Alphabetical List sigpending ========== Syntax ------ #include <signal.h> int sigpending (sigset_t *set) Description ----------- This function retrieves the signals that have been sent to the program, but are being blocked from delivery by the program's signal mask (*note sigprocmask::.). The bit-mapped value which describes the pending signals is stored in the structure pointed to by SET. You can use the `sigismember' function (*note sigismember::.) to see what individual signals are pending. Return Value ------------ 0 on success, -1 on failure (and errno set to `EFAULT'). Portability ----------- not ANSI, POSIX Example ------- #include <signal.h> sigset_t pending_signals; /* If SIGINT is pending, force it to be raised. */ if (sigpending (&pending_signals) == 0 && sigismember (&pending_signals, SIGINT)) { sigset_t new_set, old_set; sigemptyset (&new_set); sigaddset (&new_set, SIGINT); sigprocmask (SIG_UNBLOCK, &new_set, &old_set); /* will raise SIGINT */ sigprocmask (SIG_SETMASK, &old_set, &new_set); /* restore mask */ } File: libc.info, Node: sigprocmask, Next: sigsetjmp, Prev: sigpending, Up: Alphabetical List sigprocmask =========== Syntax ------ #include <signal.h> int sigprocmask (int how, const sigset_t *new_set, sigset_t *old_set) Description ----------- This function is used to examine and/or change the program's current signal mask. The current signal mask determines which signals are blocked from being delivered to the program. A signal is blocked if its bit in the mask is set. (*Note sigismember::, *Note sigaddset::, *Note sigdelset::, *Note sigemptyset::, *Note sigfillset::, for information about functions to manipulate the signal masks.) When a blocked signal happens, it is not delivered to the program until such time as that signal is unblocked by another call to `sigprocmask'. Thus blocking a signal is an alternative to ignoring it (by setting its handler to `SIG_IGN', *note signal::.), but has an advantage of not missing the signal entirely. The value of the argument HOW determines the operation: if it is `SIG_BLOCK', the set pointed to by the argument NEW_SET is *added* to the current signal mask. If the value is `SIG_UNBLOCK', the set pointed to by NEW_SET is *removed* from the current signal mask. If the value is `SIG_SETMASK', the current mask is *replaced* by the set pointed to by NEW_SET. If the argument OLD_SET is not `NULL', the previous mask is stored in the space pointed to by OLD_SET. If the value of the argument NEW_SET is `NULL', the value of HOW is not significant and the process signal mask is unchanged; thus, the call with a zero NEW_SET can be used to inquire about currently blocked signals, without changing the current set. If the new set defined by the call causes some pending signals to be unblocked, they are all delivered (by calling `raise') before the call to `sigprocmask' returns. The DJGPP implementation only records a single occurrence of any given signal, so when the signal is unblocked, its handler will be called at most once. It is not possible to block CPU exceptions such as Page Fault, General Protection Fault etc. (mapped to `SIGSEGV' signal); for these, `sigprocmask' will behave as if the call succeeded, but when an exception happens, the signal handler will be called anyway (the default handler will abort the program). Also note that there are no provisions to save and restore any additional info about the signal beyond the fact that it happened. A signal handler might need such info to handle the signal intelligently. For example, a handler for `SIGFPE' might need to examine the status word of the FPU to see what exactly went wrong. But if the signal was blocked and is delivered after a call to `sigprocmask' has unblocked it, that information is lost. Therefore, if you need access to such auxiliary information in the signal handler, don't block that signal. Return Value ------------ 0 on success, -1 for illegal value of SIG or illegal address in NEW_SET or OLD_SET. Portability ----------- not ANSI, POSIX Example ------- #include <conio.h> #include <signal.h> static void sig_catcher (int signo) { cprintf ("\r\nGot signal %d\r\n", signo); } int main (void) { sigset_t sigmask, prevmask; signal (SIGINT, sig_catcher); sigemptyset (&sigmask); sigaddset (&sigmask, SIGINT); if (sigprocmask (SIG_SETMASK, &sigmask, &prevmask) == 0) cputs ("SIGINT blocked. Try to interrupt me now.\r\n"); while (!kbhit ()) ; cputs ("See? I wasn't interrupted.\r\n"); cputs ("But now I will unblock SIGINT, and then get the signal.\r\n"); sigprocmask (SIG_UNBLOCK, &sigmask, &prevmask); return 0; } File: libc.info, Node: sigsetjmp, Next: sin, Prev: sigprocmask, Up: Alphabetical List sigsetjmp ========= Syntax ------ #include <setjmp.h> int sigsetjmp(sigjmp_buf env, int savemask); Description ----------- *Note setjmp::. Portability ----------- not ANSI, POSIX File: libc.info, Node: sin, Next: sincos, Prev: sigsetjmp, Up: Alphabetical List sin === Syntax ------ #include <math.h> double sin(double x); Description ----------- This function computes the sine of X (which should be given in radians). Return Value ------------ The sine of X. If the absolute value of X is finite but greater than or equal to 2^63, the value is 0 (since for arguments that large each bit of the mantissa is more than `Pi'). If the value of X is infinite or `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX Accuracy -------- In general, this function's relative accuracy is about 1.7*10^(-16), which is close to the machine precision for a `double'. However, for arguments very close to `Pi' and its odd multiples, the relative accuracy can be many times worse, due to loss of precision in the internal FPU computations. Since sin(Pi) is zero, the absolute accuracy is still very good; but if your program needs to preserve high *relative* accuracy for such arguments, link with `-lm' and use the version of `sin' from `libm.a' which does elaborate argument reduction, but is about three times slower. File: libc.info, Node: sincos, Next: sinh, Prev: sin, Up: Alphabetical List sincos ====== Syntax ------ #include <math.h> void sincos(double *cosine, double *sine, double x); Description ----------- This function computes the cosine and the sine of X in a single call, and stores the results in the addresses pointed to by COSINE and SINE, respectively. Since the function exploits a machine instruction that computes both cosine and sine simultaneously, it is faster to call `sincos' than to call `cos' and `sin' for the same argument. If the absolute value of X is finite but greater than or equal to 2^63, the value stored in *COSINE is 1 and the value stored in *SINE is 0 (since for arguments that large each bit of the mantissa is more than `Pi'). If the value of X is infinite or `NaN', `NaN' is stored in both *COSINE and *SINE, and `errno' is set to `EDOM'. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: sinh, Next: sleep, Prev: sincos, Up: Alphabetical List sinh ==== Syntax ------ #include <math.h> double sinh(double x); Description ----------- This function computes the hyperbolic sine of X. Return Value ------------ The hyperbolic sine of X. If the absolute value of X is finite but so large that the result would overflow a `double', the return value is `Inf' with the same sign as X, and `errno' is set to `ERANGE'. If X is either a positive or a negative infinity, the result is `+Inf' with the same sign as X, and `errno' is not changed. If X is `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: sleep, Next: sound, Prev: sinh, Up: Alphabetical List sleep ===== Syntax ------ #include <unistd.h> unsigned sleep(unsigned seconds); Description ----------- This function causes the program to pause for SECONDS seconds. Return Value ------------ The number of seconds that haven't passed (i.e. always zero) Portability ----------- not ANSI, POSIX Example ------- sleep(5); File: libc.info, Node: sound, Next: spawn*, Prev: sleep, Up: Alphabetical List sound ===== Syntax ------ #include <pc.h> void sound(int _frequency); Description ----------- Enables the PC speaker at the given frequency. The argument _FREQUENCY should be given in Hertz units. Portability ----------- not ANSI, not POSIX File: libc.info, Node: spawn*, Next: sprintf, Prev: sound, Up: Alphabetical List spawn* ====== Syntax ------ #include <process.h> int spawnl(int mode, const char *path, const char *argv0, ..., NULL); int spawnle(int mode, const char *path, const char *argv0, ..., NULL /*, const char **envp */); int spawnlp(int mode, const char *path, const char *argv0, ..., NULL); int spawnlpe(int mode, const char *path, const char *argv0, ..., NULL /*, const char **envp */); int spawnv(int mode, const char *path, const char **argv); int spawnve(int mode, const char *path, const char **argv, const char **envp); int spawnvp(int mode, const char *path, const char **argv); int spawnvpe(int mode, const char *path, const char **argv, const char **envp); Description ----------- These functions run other programs. The PATH points to the program to run, and may optionally include its extension. These functions will look for a file PATH with the extensions `.com', `.exe', `.bat', `.btm', `.sh', `.ksh', `.pl' and `.sed'; if none is found, neither in the current directory nor along the `PATH', they will look for PATH itself. `.com' programs are invoked via the usual DOS calls; DJGPP `.exe' programs are invoked in a way that allows long command lines to be passed; other `.exe' programs are invoked via DOS; `.bat' and `.btm' programs are invoked via the command processor given by the `COMSPEC' environment variable; `.sh', `.ksh' programs and programs with any other extensions that have `#!' as their first two characters are assumed to be Unix-style scripts and are invoked by calling a program whose pathname immediately follows the first two characters. (If the name of that program is a Unix-style pathname, without a drive letter and without an extension, like `/bin/sh', the `spawn' functions will additionally look them up on the `PATH'; this allows to run Unix scripts without editing, if you have a shell installed somewhere along your `PATH'.) Any non-recognizable files will be also invoked via DOS calls. *WARNING!* DOS is rather stupid in invoking programs: if the file doesn't have the telltale "MZ" signature of the `.exe' style programs, DOS assumes it is a `.com' style image and tries to execute it directly. If the file is not really an executable program, your application will almost certainly crash. Applications that need to be robust in such situations should test whether the program file is indeed an executable, e.g. with calls to `stat' (*note stat::.) or `_is_executable' (*note _is_executable::.) library functions. Note that built-in commands of the shells can *not* be invoked via these functions; use `system' instead, or invoke the appropriate shell with the built-in command as its argument. The programs are invoked with the arguments given. The zeroth argument is normally not used, since MS-DOS cannot pass it separately, but for compatibility it should be the name of the program. There are two ways of passing arguments. The `l' functions (like `spawnl') take a list of arguments, with a `NULL' at the end of the list. This is useful when you know how many argument there will be ahead of time. The `v' functions (like `spawnv') take a pointer to a list of arguments, which also must be `NULL'-terminated. This is useful when you need to compute the number of arguments at runtime. In either case, you may also specify `e' to indicate that you will be giving an explicit environment, else the current environment is used. You may also specify `p' to indicate that you would like `spawn*' to search the `PATH' (in either the environment you pass or the current environment) for the executable, else it will only check the explicit path given. Note that these function understand about other DJGPP programs, and will call them directly, so that you can pass command lines longer than 126 characters to them without any special code. DJGPP programs called by these functions will *not* glob the arguments passed to them; other programs also won't glob the arguments if they suppress expansion when given quoted filenames. *Note exec*::. Return Value ------------ If successful and `mode' is `P_WAIT', these functions return the exit code of the child process in the lower 8 bits of the return value. Note that if the program is run by a command processor (e.g., if it's a batch file), the exit code of that command processor will be returned. `COMMAND.COM' is notorious for returning 0 even if it couldn't run the command. If successful and MODE is `P_OVERLAY', these functions will not return. If there is an error (e.g., the program specified as `argv[0]' cannot be run, or the command line is too long), these functions return -1 and set `errno' to indicate the error. If the child program was interrupted by <Ctrl-C> or a Critical Device error, `errno' is set to `EINTR' (even if the child's exit code is 0), and bits 8-17 of the return value are set to `SIGINT' or `SIGABRT', accordingly. Note that you must set the signal handler for `SIGINT' to `SIG_IGN', or arrange for the handler to return, or else your program will be aborted before it will get chance to set the value of the return code. Portability ----------- not ANSI, not POSIX Example ------- char *environ[] = { "PATH=c:\\dos;c:\\djgpp;c:\\usr\\local\\bin", "DJGPP=c:/djgpp", 0 }; char *args[] = { "gcc", "-v", "hello.c", 0 }; spawnvpe(P_WAIT, "gcc", args, environ); File: libc.info, Node: sprintf, Next: sqrt, Prev: spawn*, Up: Alphabetical List sprintf ======= Syntax ------ #include <stdio.h> int sprintf(char *buffer, const char *format, ...); Description ----------- Sends formatted output from the arguments (...) to the BUFFER. *Note printf::. Return Value ------------ The number of characters written. Portability ----------- ANSI, POSIX File: libc.info, Node: sqrt, Next: srand, Prev: sprintf, Up: Alphabetical List sqrt ==== Syntax ------ #include <math.h> double sqrt(double x); Description ----------- This function computes the square root of X. Return Value ------------ The square root of X. If X is negative or a `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: srand, Next: srandom, Prev: sqrt, Up: Alphabetical List srand ===== Syntax ------ #include <stdlib.h> void srand(unsigned seed); Description ----------- Initializes the random number generator for `rand()'. If you pass the same seed, `rand()' will return the same sequence of numbers. You can seed from *Note time:: or *Note rawclock::. Portability ----------- ANSI, POSIX Example ------- /* random pause */ srand(time(0)); for (i=rand(); i; i--); File: libc.info, Node: srandom, Next: sscanf, Prev: srand, Up: Alphabetical List srandom ======= Syntax ------ #include <stdlib.h> int srandom(int seed); Description ----------- Initializes the random number generator (*note random::.). Passing the same SEED results in `random' returning predictable sequences of numbers, unless *note initstate::. or *note setstate::. are called. Return Value ------------ Zero. Portability ----------- not ANSI, not POSIX Example ------- srandom(45); File: libc.info, Node: sscanf, Next: stackavail, Prev: srandom, Up: Alphabetical List sscanf ====== Syntax ------ #include <stdio.h> int sscanf(const char *string, const char *format, ...); Description ----------- This function scans formatted text from the STRING and stores it in the variables pointed to by the arguments. *Note scanf::. Return Value ------------ The number of items successfully scanned. Portability ----------- ANSI, POSIX File: libc.info, Node: stackavail, Next: stat, Prev: sscanf, Up: Alphabetical List stackavail ========== Syntax ------ #include <stdlib.h> int stackavail(void); Description ----------- This function returns the number of bytes that are available on the stack. Portability ----------- not ANSI, not POSIX Example ------- printf("Available stack size is %d bytes\n", stackavail()); File: libc.info, Node: stat, Next: statfs, Prev: stackavail, Up: Alphabetical List stat ==== Syntax ------ #include <sys/stat.h> int stat(const char *file, struct stat *sbuf); Description ----------- This function obtains the status of the file FILE and stores it in SBUF, which has this structure: struct stat { time_t st_atime; /* time of last access */ time_t st_ctime; /* time of file's creation */ dev_t st_dev; /* The drive number (0 = a:) */ gid_t st_gid; /* what getgid() returns */ ino_t st_ino; /* starting cluster or unique identifier */ mode_t st_mode; /* file mode - S_IF* and S_IRUSR/S_IWUSR */ time_t st_mtime; /* time that the file was last written */ nlink_t st_nlink; /* 2 + number of subdirs, or 1 for files */ off_t st_size; /* size of file in bytes */ off_t st_blksize; /* the size of transfer buffer */ uid_t st_uid; /* what getuid() returns */ }; The `st_atime', `st_ctime' and `st_mtime' have different values only when long file names are supported (e.g. on Windows 9X); otherwise, they all have the same value: the time that the file was last written(1). Most Windows 9X VFAT filesystems only support the date of the file's last access (the time is set to zero); therefore, the DJGPP implementation of `stat' sets the `st_atime' member to the same value as `st_mtime' if the time part of `st_atime' returned by the filesystem is zero (to prevent the situation where the file appears to have been created *after* it was last accessed, which doesn't look good). Some members of `struct stat' are very expensive to compute. If your application is a heavy user of `stat' and is too slow, you can disable computation of the members your application doesn't need, as described in *Note _djstat_flags::. Return Value ------------ Zero on success, nonzero on failure (and ERRNO set). Portability ----------- not ANSI, POSIX Example ------- struct stat s; stat("data.txt", &s); if (S_ISDIR(s.st_mode)) printf("is directory\n"); Implementation Notes -------------------- Supplying a 100% Unix-compatible `stat' function under DOS is an implementation nightmare. The following notes describe some of the obscure points specific to `stat's behavior in DJGPP. 1. The `drive' for character devices (like `con', `/dev/null' and others is returned as -1. For drives networked by Novell Netware, it is returned as -2. 2. The starting cluster number of a file serves as its inode number. For files whose starting cluster number is inaccessible (empty files, files on Windows 9X, on networked drives, etc.) the `st_inode' field will be *invented* in a way which guarantees that no two different files will get the same inode number (thus it is unique). This invented inode will also be different from any real cluster number of any local file. However, only on plain DOS, and only for local, non-empty files/directories the inode is guaranteed to be consistent between `stat' and `fstat' function calls. 3. The WRITE access mode bit is set only for the user (unless the file is read-only, hidden or system). EXECUTE bit is set for directories, files which can be executed from the DOS prompt (batch files, .com, .dll and .exe executables) or run by `go32-v2'. 4. Size of directories is reported as the number of its files (sans `.' and `..' entries) multiplied by 32 bytes (the size of directory entry). On FAT filesystems that support the LFN API (such as Windows 9X), the reported size of the directory accounts for additional space used to store the long file names. 5. Time stamp for root directories is taken from the volume label entry, if that's available; otherwise, it is reported as 1-Jan-1980. 6. The variable `_djstat_flags' (*note _djstat_flags::.) controls what hard-to-get fields of `struct stat' are needed by the application. 7. `stat' should not be used to get an up-to-date info about a file which is open and has been written to, because `stat' will only return correct data after the file is closed. Use `fstat' (*note fstat::.) while the file is open. Alternatively, you can call `fflush' and `fsync' to make the OS flush all the file's data to the disk, before calling `stat'. 8. The number of links `st_nlink' is always 1 for files other than directories. For directories, it is the number of subdirectories plus 2. This is so that programs written for Unix that depend on this to optimize recursive traversal of the directory tree, will still work. ---------- Footnotes ---------- (1) Even when long file names *are* supported, the three time values returned by `stat' might be identical if the file was last written by a program which used legacy DOS functions that don't know about long file names. File: libc.info, Node: statfs, Next: _status87, Prev: stat, Up: Alphabetical List statfs ====== Syntax ------ #include <sys/vfs.h> int statfs(const char *filename, struct statfs *buf); Description ----------- This function returns information about the given "filesystem". The drive letter of the given FILENAME, or the default drive if none is given, is used to retrieve the following structure: struct statfs { long f_type; /* 0 */ long f_bsize; /* bytes per cluster */ long f_blocks; /* clusters on drive */ long f_bfree; /* available clusters */ long f_bavail; /* available clusters */ long f_files; /* clusters on drive */ long f_ffree; /* available clusters */ fsid_t f_fsid; /* [0]=drive_number, [1]=MOUNT_UFS long f_magic; /* FS_MAGIC */ }; Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- struct statfs fs; statfs("anything", &fs); printf("%d bytes left\n", fs.f_bfree * fs.f_bsize); File: libc.info, Node: _status87, Next: _stklen, Prev: statfs, Up: Alphabetical List _status87 ========= Syntax ------ #include <float.h> unsigned int _status87(void); Description ----------- Returns the status word of the FPU, which indicate the results of the most recently completed FPU operation: ---- ---- ---- ---X = SW_INVALID - invalid operation ---- ---- ---- --X- = SW_DENORMAL - denormalized operand ---- ---- ---- -X-- = SW_ZERODIVIDE - division by zero ---- ---- ---- X--- = SW_OVERFLOW - overflow ---- ---- ---X ---- = SW_UNDERFLOW - underflow ---- ---- --X- ---- = SW_INEXACT - loss of precision ---- ---- -X-- ---- = SW_STACKFAULT - stack over/under flow ---- ---- X--- ---- = SW_ERRORSUMMARY - set if any errors -X-- -XXX ---- ---- = SW_COND - condition code ---- ---X ---- ---- = SW_C0 ---- --X- ---- ---- = SW_C1 ---- -X-- ---- ---- = SW_C2 -X-- ---- ---- ---- = SW_C3 --XX X--- ---- ---- = SW_TOP - top of stack (use SW_TOP_SHIFT to shift it) X--- ---- ---- ---- = SW_BUSY - fpu is busy Portability ----------- not ANSI, not POSIX File: libc.info, Node: _stklen, Next: stpcpy, Prev: _status87, Up: Alphabetical List _stklen ======= Syntax ------ extern int _stklen; Description ----------- This variable sets the minimum stack length that the program requires. Note that the stack may be much larger than this. This value should be set statically, as it is only used at startup. Portability ----------- not ANSI, not POSIX Example ------- int _stklen = 256000; File: libc.info, Node: stpcpy, Next: strcasecmp, Prev: _stklen, Up: Alphabetical List stpcpy ====== Syntax ------ #include <string.h> char *stpcpy(char *_dest, const char *_src); Description ----------- Like `strcpy' (*note strcpy::.), but return value different. Return Value ------------ Returns a pointer to the trailing NUL in DEST. Portability ----------- not ANSI, not POSIX File: libc.info, Node: strcasecmp, Next: strcat, Prev: stpcpy, Up: Alphabetical List strcasecmp ========== Syntax ------ #include <string.h> int strcasecmp(const char *s1, const char *s2); Description ----------- This function compares the two strings, disregarding case. Return Value ------------ Zero if they're the same, nonzero if different, the sign indicates "order". Portability ----------- not ANSI, not POSIX Example ------- if (strcasecmp(arg, "-i") == 0) do_include(); File: libc.info, Node: strcat, Next: strchr, Prev: strcasecmp, Up: Alphabetical List strcat ====== Syntax ------ #include <string.h> char *strcat(char *s1, const char *s2); Description ----------- This function concatenates S2 to the end of S1. Return Value ------------ S1 Portability ----------- ANSI, POSIX Example ------- char buf[100] = "hello"; strcat(buf, " there"); File: libc.info, Node: strchr, Next: strcmp, Prev: strcat, Up: Alphabetical List strchr ====== Syntax ------ #include <string.h> char *strchr(const char *s, int c); Description ----------- This function returns a pointer to the first occurrence of C in S. Note that if C is `NULL', this will return a pointer to the end of the string. Return Value ------------ A pointer to the character, or `NULL' if it wasn't found. Portability ----------- ANSI, POSIX Example ------- char *slash = strchr(filename, '/'); File: libc.info, Node: strcmp, Next: strcoll, Prev: strchr, Up: Alphabetical List strcmp ====== Syntax ------ #include <string.h> int strcmp(const char *s1, const char *s2); Description ----------- This function compares S1 and S2. Return Value ------------ Zero if the strings are equal, a positive number if S1 comes after S2 in the ASCII collating sequense, else a negative number. Portability ----------- ANSI, POSIX Example ------- if (strcmp(arg, "-i") == 0) do_include(); File: libc.info, Node: strcoll, Next: strcpy, Prev: strcmp, Up: Alphabetical List strcoll ======= Syntax ------ #include <string.h> int strcoll(const char *s1, const char *s2); Description ----------- This function compares S1 and S2, using the collating sequences from the current locale. Return Value ------------ Zero if the strings are equal, a positive number if S1 comes after S2 in the collating sequense, else a negative number. Portability ----------- ANSI, POSIX Example ------- while (strcoll(var, list[i]) < 0) i++; File: libc.info, Node: strcpy, Next: strcspn, Prev: strcoll, Up: Alphabetical List strcpy ====== Syntax ------ #include <string.h> char *strcpy(char *s1, const char *s2); Description ----------- This function copies S2 into S1. Return Value ------------ S1 Portability ----------- ANSI, POSIX Example ------- char buf[100]; strcpy(buf, arg); File: libc.info, Node: strcspn, Next: strdup, Prev: strcpy, Up: Alphabetical List strcspn ======= Syntax ------ #include <string.h> size_t strcspn(const char *s1, const char *set); Description ----------- This function finds the first character in S1 that matches any character in SET. Note that the `NULL' bytes at the end of each string counts, so you'll at least get a pointer to the end of the string if nothing else. Return Value ------------ The index of the found character. Portability ----------- ANSI, POSIX Example ------- int i = strcspn(command, "<>|"); if (command[i]) do_redirection(); File: libc.info, Node: strdup, Next: strerror, Prev: strcspn, Up: Alphabetical List strdup ====== Syntax ------ #include <string.h> char * strdup (const char *source); Description ----------- Returns a newly allocated area of memory that contains a duplicate of the string pointed to by SOURCE. The memory returned by this call must be freed by the caller. Return Value ------------ Returns the newly allocated string, or NULL if there is no more memory. Portability ----------- not ANSI, not POSIX Example ------- char *foo() { return strdup("hello"); } File: libc.info, Node: strerror, Next: strftime, Prev: strdup, Up: Alphabetical List strerror ======== Syntax ------ #include <string.h> char *strerror(int error); Description ----------- This function returns a string that describes the ERROR. Return Value ------------ A pointer to a static string that should not be modified or free'd. Portability ----------- ANSI, POSIX Example ------- if (f=fopen("foo", "r") == 0) printf("Error! %s: %s\n", "foo", strerror(errno)); File: libc.info, Node: strftime, Next: stricmp, Prev: strerror, Up: Alphabetical List strftime ======== Syntax ------ #include <time.h> size_t strftime(char *buf, size_t n, const char *format, const struct tm *time_info); Description ----------- This function formats the time data in TIME_INFO according to the given FORMAT and stores it in BUF, not exceeding N bytes. The format string is like `printf' in that any character other than `%' is added to the output string, and for each character following a `%' a pattern is added to the string as follows, with the examples as if the time was Friday, October 1, 1993, at 03:30:34 PM EDT: `%A' The full weekday name (`Friday') `%a' The abbreviated weekday name (`Fri') `%B' The full month name (`October') `%b' `%h' The abbreviated month name (`Oct') `%C' Short for `%a %b %e %H:%M:%S %Y' (`Fri Oct 1 15:30:34 1993') `%c' Short for `%m/%d/%y %H:%M:%S' (`10/01/93 15:30:34') `%e' The day of the month, blank padded to two characters (` 2') `%D' Short for `%m/%d/%y' (`10/01/93') `%d' The day of the month, zero padded to two characters (`02') `%H' The hour (0-24), zero padded to two characters (`15') `%I' The hour (1-12), zero padded to two characters (`03') `%j' The Julian day, zero padded to three characters (`275') `%k' The hour (0-24), space padded to two characters (`15') `%l' The hour (1-12), space padded to two characters(` 3') `%M' The minutes, zero padded to two characters (`30') `%m' The month (1-12), zero padded to two characters (`10') `%n' A newline (`\n') `%p' AM or PM (`PM') `%R' Short for `%H:%M' (`15:30') `%r' Short for `%I:%M:%S %p' (`03:30:35 PM') `%S' The seconds, zero padded to two characters (`35') `%T' `%X' Short for `%H:%M:%S' (`15:30:35') `%t' A tab (`\t') `%U' The week of the year, with the first week defined by the first Sunday of the year, zero padded to two characters (`39') `%u' The day of the week (1-7) (`6') `%W' The week of the year, with the first week defined by the first Monday of the year, zero padded to two characters (`39') `%w' The day of the week (0-6) (`5') `%x' Short for `%m/%d/%y' (`10/01/93') `%y' The year (00-99) of the century (`93') `%Y' The year, zero padded to four digits (`1993') `%Z' The timezone abbreviation (`EDT') `%%' A percent symbol (`%') Return Value ------------ The number of characters stored. Portability ----------- ANSI, POSIX Example ------- time_t now = time (NULL); struct tm *t = localtime (&now); char buf[100]; /* Print today's date e.g. "January 31, 2001". */ strftime (buf, 100, "%B %d, %Y", t); File: libc.info, Node: stricmp, Next: strlen, Prev: strftime, Up: Alphabetical List stricmp ======= Syntax ------ #include <string.h> int stricmp(const char *s1, const char *s2); Description ----------- This function compares the two strings, disregarding case. Return Value ------------ Zero if they're the same, nonzero if different, the sign indicates "order". Portability ----------- not ANSI, not POSIX Example ------- if (stricmp(arg, "-i") == 0) do_include(); File: libc.info, Node: strlen, Next: strlwr, Prev: stricmp, Up: Alphabetical List strlen ====== Syntax ------ #include <string.h> size_t strlen(const char *string); Description ----------- This function returns the number of characters in STRING. Return Value ------------ The length of the string. Portability ----------- ANSI, POSIX Example ------- if (strlen(fname) > PATH_MAX) invalid_file(fname); File: libc.info, Node: strlwr, Next: strncasecmp, Prev: strlen, Up: Alphabetical List strlwr ====== Syntax ------ #include <string.h> char *strlwr(char *string); Description ----------- This function replaces all upper case letters in STRING with lower case letters. Return Value ------------ The string. Portability ----------- not ANSI, not POSIX Example ------- char buf[100] = "Hello"; strlwr(buf); File: libc.info, Node: strncasecmp, Next: strncat, Prev: strlwr, Up: Alphabetical List strncasecmp =========== Syntax ------ #include <string.h> int strncasecmp(const char *s1, const char *s2, size_t max); Description ----------- This function compares S1 and S2, ignoring case, up to a maximum of MAX characters. Return Value ------------ Zero if the strings are equal, a positive number if S1 comes after S2 in the ASCII collating sequense, else a negative number. Portability ----------- not ANSI, not POSIX Example ------- if (strncasecmp(foo, "-i", 2) == 0) do_include(); File: libc.info, Node: strncat, Next: strncmp, Prev: strncasecmp, Up: Alphabetical List strncat ======= Syntax ------ #include <string.h> char *strncat(char *s1, const char *s2, size_t max); Description ----------- This function concatenates up to MAX characters of S2 to the end of S1. Return Value ------------ S1 Portability ----------- ANSI, POSIX Example ------- strncat(fname, extension, 4); File: libc.info, Node: strncmp, Next: strncpy, Prev: strncat, Up: Alphabetical List strncmp ======= Syntax ------ #include <string.h> int strncmp(const char *s1, const char *s2, size_t max); Description ----------- This function compares up to MAX characters of S1 and S2. Return Value ------------ Zero if the strings are equal, a positive number if S1 comes after S2 in the ASCII collating sequense, else a negative number. Portability ----------- ANSI, POSIX Example ------- if (strncmp(arg, "-i", 2) == 0) do_include(); File: libc.info, Node: strncpy, Next: strnicmp, Prev: strncmp, Up: Alphabetical List strncpy ======= Syntax ------ #include <string.h> char *strncpy(char *s1, const char *s2, size_t max); Description ----------- This function copies up to MAX characters of S2 into S1. Return Value ------------ S1 Portability ----------- ANSI, POSIX Example ------- char buf[100]; strncpy(buf, arg, 99); File: libc.info, Node: strnicmp, Next: strpbrk, Prev: strncpy, Up: Alphabetical List strnicmp ======== Syntax ------ #include <string.h> int strnicmp(const char *s1, const char *s2, size_t max); Description ----------- This function compares S1 and S2, ignoring case, up to a maximum of MAX characters. Return Value ------------ Zero if the strings are equal, a positive number if S1 comes after S2 in the ASCII collating sequense, else a negative number. Portability ----------- not ANSI, not POSIX Example ------- if (strnicmp(foo, "-i", 2) == 0) do_include(); File: libc.info, Node: strpbrk, Next: strrchr, Prev: strnicmp, Up: Alphabetical List strpbrk ======= Syntax ------ #include <string.h> char *strpbrk(const char *s1, const char *set); Description ----------- This function finds the first character in S1 that matches any character in SET. Return Value ------------ A pointer to the first match, or `NULL' if none are found. Portability ----------- ANSI, POSIX Example ------- if (strpbrk(command, "<>|")) do_redirection(); File: libc.info, Node: strrchr, Next: strsep, Prev: strpbrk, Up: Alphabetical List strrchr ======= Syntax ------ #include <string.h> char *strrchr(const char *s1, int c); Description ----------- This function finds the last occurrence of `c' in `s1'. Return Value ------------ A pointer to the last match, or `NULL' if the character isn't in the string. Portability ----------- ANSI, POSIX Example ------- char *last_slash = strrchr(filename, '/'); File: libc.info, Node: strsep, Next: strspn, Prev: strrchr, Up: Alphabetical List strsep ====== Syntax ------ #include <string.h> char *strsep(char **stringp, char *delim); Description ----------- This function retrieves the next token from the given string, where STRINGP points to a variable holding, initially, the start of the string. Tokens are delimited by a character from DELIM. Each time the function is called, it returns a pointer to the next token, and sets *STRINGP to the next spot to check, or `NULL'. Return Value ------------ The next token, or NULL. Portability ----------- not ANSI, not POSIX Example ------- main() { char *buf = "Hello there,stranger"; char **bp = &buf; char *tok; while (tok = strsep(bp, " ,")) printf("tok = `%s'\n", tok); } tok = `Hello' tok = `' tok = `there' tok = `stranger' File: libc.info, Node: strspn, Next: strstr, Prev: strsep, Up: Alphabetical List strspn ====== Syntax ------ #include <string.h> size_t strspn(const char *s1, const char *set); Description ----------- This function finds the first character in S1 that does not match any character in SET. Note that the `NULL' bytes at the end of S1 counts, so you'll at least get a pointer to the end of the string if nothing else. Return Value ------------ The index of the found character. Portability ----------- ANSI, POSIX Example ------- int i = strspn(entry, " \t\b"); if (entry[i]) do_something(); File: libc.info, Node: strstr, Next: strtod, Prev: strspn, Up: Alphabetical List strstr ====== Syntax ------ #include <string.h> char *strstr(const char *s1, const char *s2); Description ----------- This function finds the first occurrence of S2 in S1. Return Value ------------ A pointer within S1, or `NULL' if S2 wasn't found. Portability ----------- ANSI, POSIX Example ------- if (strstr(command, ".exe")) do_exe(); File: libc.info, Node: strtod, Next: strtok, Prev: strstr, Up: Alphabetical List strtod ====== Syntax ------ #include <stdlib.h> double strtod(const char *s, char **endp); Description ----------- This function converts as many characters of S as look like a floating point number into that number. If ENDP is not a null pointer, `*endp' is set to point to the first unconverted character. Return Value ------------ The value the represented by S. If a number represented by S doesn't fit into the range of values representable by the type `double', the function returns either `-HUGE_VAL' (if S begins with the character `-') or `+HUGE_VAL', and sets `errno' to `ERANGE'. Portability ----------- ANSI, POSIX Example ------- char *buf = "123ret"; char *bp; double x = strtod(buf, &bp); File: libc.info, Node: strtok, Next: strtol, Prev: strtod, Up: Alphabetical List strtok ====== Syntax ------ #include <string.h> char *strtok(char *s1, const char *s2); Description ----------- This function retrieves tokens from S1 which are delimited by characters from S2. To initiate the search, pass the string to be searched as S1. For the remaining tokens, pass `NULL' instead. Return Value ------------ A pointer to the token, or `NULL' if no more are found. Portability ----------- ANSI, POSIX Example ------- main() { char *buf = "Hello there, stranger"; char *tok; for (tok = strtok(buf, " ,"); tok; tok=strtok(0, " ,")) printf("tok = `%s'\n", tok); } tok = `Hello' tok = `there' tok = `stranger' File: libc.info, Node: strtol, Next: _strtold, Prev: strtok, Up: Alphabetical List strtol ====== Syntax ------ #include <stdlib.h> long strtol(const char *s, char **endp, int base); Description ----------- This function converts as much of S as looks like an appropriate number into the value of that number. If ENDP is not a null pointer, *ENDP is set to point to the first unused character. The BASE argument indicates what base the digits (or letters) should be treated as. If BASE is zero, the base is determined by looking for `0x', `0X', or `0' as the first part of the string, and sets the base used to 16, 16, or 8 if it finds one. The default base is 10 if none of those prefixes are found. Return Value ------------ The value. Portability ----------- ANSI, POSIX Example ------- printf("Enter a number: "); fflush(stdout); gets(buf); char *bp; printf("The value is %d\n", strtol(buf, &bp, 0)); File: libc.info, Node: _strtold, Next: strtoll, Prev: strtol, Up: Alphabetical List _strtold ======== Syntax ------ #include <stdlib.h> long double _strtold(const char *s, char **endp); Description ----------- This function converts as many characters of S that look like a floating point number into one, and sets *ENDP to point to the first unused character. Return Value ------------ The value the string represented. Portability ----------- not ANSI, not POSIX Example ------- char *buf = "123ret"; char *bp; long double x = _strtold(buf, &bp); File: libc.info, Node: strtoll, Next: strtoul, Prev: _strtold, Up: Alphabetical List strtoll ======= Syntax ------ #include <stdlib.h> long long strtoll(const char *s, char **endp, int base); Description ----------- This function converts as much of S as looks like an appropriate number into the value of that number, and sets *ENDP to point to the first unused character. The BASE argument indicates what base the digits (or letters) should be treated as. If BASE is zero, the base is determined by looking for `0x', `0X', or `0' as the first part of the string, and sets the base used to 16, 16, or 8 if it finds one. The default base is 10 if none of those prefixes are found. Return Value ------------ The value. Portability ----------- not ANSI, not POSIX Example ------- printf("Enter a number: "); fflush(stdout); gets(buf); char *bp; printf("The value is %lld\n", strtoll(buf, &bp, 0)); File: libc.info, Node: strtoul, Next: strtoull, Prev: strtoll, Up: Alphabetical List strtoul ======= Syntax ------ #include <stdlib.h> unsigned long strtoul(const char *s, char **endp, int base); Description ----------- This is just like `strtol' (*note strtol::.) except that the result is unsigned. Return Value ------------ The value. Portability ----------- ANSI, POSIX Example ------- printf("Enter a number: "); fflush(stdout); gets(buf); char *bp; printf("The value is %u\n", strtoul(buf, &bp, 0)); File: libc.info, Node: strtoull, Next: strupr, Prev: strtoul, Up: Alphabetical List strtoull ======== Syntax ------ #include <stdlib.h> unsigned long long strtoull(const char *s, char **endp, int base); Description ----------- This is just like `strtoll' (*note strtoll::.) except that the result is unsigned. Return Value ------------ The value. Portability ----------- not ANSI, not POSIX Example ------- printf("Enter a number: "); fflush(stdout); gets(buf); char *bp; printf("The value is %llu\n", strtoull(buf, &bp, 0)); File: libc.info, Node: strupr, Next: strxfrm, Prev: strtoull, Up: Alphabetical List strupr ====== Syntax ------ #include <string.h> char *strupr(char *string); Description ----------- This function converts all lower case characters in STRING to upper case. Return Value ------------ STRING Portability ----------- not ANSI, not POSIX Example ------- char buf[] = "Foo!"; strupr(buf); File: libc.info, Node: strxfrm, Next: swab, Prev: strupr, Up: Alphabetical List strxfrm ======= Syntax ------ #include <string.h> size_t strxfrm(char *s1, const char *s2, size_t max); Description ----------- This copies characters from S2 to S1, which must be able to hold MAX characters. Each character is transformed according to the locale such that `strcmp(s1b, s2b)' is just like `strcoll(s1, s2)' where `s1b' and `s2b' are the transforms of `s1' and `s2'. Return Value ------------ The actual number of bytes required to transform S2, including the `NULL'. Portability ----------- ANSI, POSIX File: libc.info, Node: swab, Next: symlink, Prev: strxfrm, Up: Alphabetical List swab ==== Syntax ------ #include <stdlib.h> void swab(const void *from, void *to, int nbytes); Description ----------- This function copies NBYTES bytes from the address pointed to by FROM to the address pointed by TO, exchanging adjacent even and odd bytes. It is useful for carrying binary data between little-endian and big-endian machines. The argument NBYTES should be even, and the buffers FROM and TO should not overlap. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: symlink, Next: syms_init, Prev: swab, Up: Alphabetical List symlink ======= Syntax ------ #include <unistd.h> int symlink(const char *exists, const char *new); Description ----------- MSDOS doesn't support symbolic links. However, DJGPP supports "symlinks" to DJGPP programs. This function simulates a symlink between two `.exe' files in the DJGPP style. It creates a program whose name is pointed to by NEW which, when run, will actually execute the program EXISTS passing it the string pointed by NEW in `argv[0]' (some programs change their behavior depending on what's passed in `argv[0]'). The file referred to by EXISTS doesn't really have to exist when this function is called. If EXISTS points to an *existing* file, the function checks that it is a DJGPP executable; if not, the call will fail with `EXDEV'. Both NEW and EXISTS can point to a name with or without the `.exe' extension. Note that both EXISTS and NEW must specify file names which reside in the same directory (this is a restriction of the DJGPP "symlinks"); the function will fail and set `errno' to `EXDEV' if they aren't. This functions runs the `stubify' and `stubedit' programs, so they should be somewhere on your `PATH' for the function to succeed. (These programs come with the DJGPP development distribution.) Return Value ------------ Zero in case of success, -1 in case of failure (and `errno' set to the appropriate error code). Portability ----------- not ANSI, not POSIX Example ------- symlink ("c:/djgpp/bin/grep", "c:/djgpp/bin/fgrep"); File: libc.info, Node: syms_init, Next: syms_line2val, Prev: symlink, Up: Alphabetical List syms_init ========= Syntax ------ #include <debug/syms.h> void syms_init (char *file); Description ----------- This function reads debugging symbols from the named FILE, which should be an executable program (either a `.exe' file or a raw COFF image created by `ld.exe', the linker). It then processes the symbols: classifies them by type, sorts them by name and value, and stores them in internal data structures used by other symbol-related functions, such as `syms_val2name', `syms_val2line', etc. You *must* call `syms_init' before calling the other `syms_*' functions. Currently, `syms_init' only supports COFF and AOUT debugging format, so programs compiled with `-gstabs' cannot be processed by it. Return Value ------------ None. not ANSI, not POSIX Example ------- syms_init("c:/foo/bar/baz.exe"); File: libc.info, Node: syms_line2val, Next: syms_listwild, Prev: syms_init, Up: Alphabetical List syms_line2val ============= Syntax ------ #include <debug/syms.h> unsigned long syms_line2val (char *filename, int lnum); Description ----------- This function returns the address of the first instruction produced from the line LNUM of the source file FILENAME that was linked into a program whose symbols were read by a previous call to `syms_init'. COFF debugging format does not support pathnames, so FILENAME should not include leading directories, just the basename. You must call `syms_init' (*note syms_init::.) before calling any of the other `syms_*' functions for the first time. Return Value ------------ The address of the first instruction produced from the line, or zero if FILENAME is not found in the symbol table or if no executable code was generated for line LNUM in FILENAME. Portability ----------- not ANSI, not POSIX Example ------- syms_init ("foo.exe"); printf ("Line 3 of foo.c is at address %lx\n", syms_line2val("foo.c", 3)); File: libc.info, Node: syms_listwild, Next: syms_module, Prev: syms_line2val, Up: Alphabetical List syms_listwild ============= Syntax ------ #include <debug/syms.h> void syms_listwild (char *pattern, void (*handler) (unsigned long addr, char type_c, char *name, char *file, int lnum)); Description ----------- This function walks through all the symbols that were read by a previous call to `syms_init' (*note syms_init::.). For each symbol whose name matches PATTERN, it invokes the user-defined function HANDLER, passing it information about that symbol: `address' the address of the symbol. `type_c' a letter that specifies the type of the symbol, as follows: `T' `t' "text", or code: usually a function. `D' `d' data: an initialized variable. `B' `b' "bss": an uninitialized variable. `F' `f' a function (in `a.out' file only). `V' `v' a set element or pointer (in `a.out' file only). `I' `i' an indirect symbol (in `a.out' file only). `U' `u' an undefined (a.k.a. unresolved) symbol. `A' `a' an absolute symbol. `name' the name of the symbol. `file' the source file name where the symbol is defined. `lnum' the line number on which the symbol is defined in the source file. Since variables and functions defined in C get prepended with an underscore `_', begin PATTERN with `_' if you want it to match C symbols. You must call `syms_init' (*note syms_init::.) before calling any of the other `syms_*' functions for the first time. Return Value ------------ None. Portability ----------- not ANSI, not POSIX Example ------- void print_sym (unsigned long addr, char type_c, char *name, char *file, int lnum) { printf (file ? "%s: %lx %c %s:%d\n" : "%s: %lx %c\n", name, addr, type_c, file ? file : "", lnum ); } int main (void) { syms_init ("foo.exe"); /* List all the symbols which begin with "___djgpp". */ syms_listwild ("___djgpp*", print_sym); return 0; } File: libc.info, Node: syms_module, Next: syms_name2val, Prev: syms_listwild, Up: Alphabetical List syms_module =========== Syntax ------ #include <debug/syms.h> char *syms_module (int nfile); Description ----------- This function returns the name of the source file (a.k.a. module) whose ordinal number in the symbol table is NFILE. You must call `syms_init' (*note syms_init::.) before calling any of the other `syms_*' functions for the first time. Return Value ------------ The name of the source file, or a `NULL' pointer if NFILE is negative or larger than the total number of modules linked into the program whose symbols were read by `syms_init'. Portability ----------- not ANSI, not POSIX File: libc.info, Node: syms_name2val, Next: syms_val2line, Prev: syms_module, Up: Alphabetical List syms_name2val ============= Syntax ------ #include <debug/syms.h> extern int undefined_symbol; extern int syms_printwhy; unsigned long syms_name2val (const char *string); Description ----------- This function returns the address of a symbol specified by STRING. STRING may be one of the following: * A number, with or without a sign, in which case the number specifies the address or an offset from an address. * A file name and a line number: `FILE#[LINE]', where FILE is the name of one of the source files linked into the program whose symbols were read by `syms_init', and LINE is a line number in that FILE. If LINE is omitted, it defaults to zero. Note that the COFF format supported by DJGPP only stores the basename of the source files, so do not specify FILE with leading directories. * A symbol name as a string. The name can be specified either with or without the leading underscore `_'. * A register name `%REG'. REG specifies the value of one of the debuggee's registers saved in the external variable `a_tss' (*note run_child::.). * Any sensible combination of the above elements, see the example below. `syms_name2val' looks up the specified file, line, and symbol in the symbol table prepared by `syms_init', finds their addresses, adds the offset, if any, and returns the result. If the specified file, line, or symbol cannot be found, `syms_name2val' returns zero and sets the global variable `undefined_symbol' to a non-zero value. If the global variable `syms_printwhy' is non-zero, an error message is printed telling which part of the argument STRING was invalid. You must call `syms_init' (*note syms_init::.) before calling any of the other `syms_*' functions for the first time. Return Value ------------ The address specified by STRING, or zero, if none found. Portability ----------- not ANSI, not POSIX Example ------- unsigned long addr1, addr2, addr3; syms_init ("foo.exe"); addr1 = syms_name2val ("foo.c#256+12"); addr2 = syms_name2val ("_main"); addr3 = syms_name2val ("struct_a_var+%eax+4"); File: libc.info, Node: syms_val2line, Next: syms_val2name, Prev: syms_name2val, Up: Alphabetical List syms_val2line ============= Syntax ------ #include <debug/syms.h> char *syms_val2line (unsigned long addr, int *line, int exact); Description ----------- This function takes an address ADDR and returns the source file name which correspond to that address. The line number in that source file is stored in the variable pointed by LINE. If EXACT is non-zero, the function succeeds only if ADDR is the first address which corresponds to some source line. You must call `syms_init' (*note syms_init::.) before calling any of the other `syms_*' functions for the first time. Return Value ------------ The name of the source file which corresponds to ADDR, or `NULL' if none was found. Portability ----------- not ANSI, not POSIX Example ------- int lineno; char *file_name; syms_init ("foo.exe"); file_name = syms_val2line (0x1c12, &lineno); printf ("The address %x is on %s, line %d\n", 0x1c12, file_name, line); File: libc.info, Node: syms_val2name, Next: sync, Prev: syms_val2line, Up: Alphabetical List syms_val2name ============= Syntax ------ #include <debug/syms.h> char *syms_val2name (unsigned long addr, unsigned long *offset); Description ----------- This function takes an address ADDR and returns the name of the closest symbol whose address is less that ADDR. If OFFSET is not a `NULL' pointer, the offset of ADDR from the symbol's address is stored in the variable pointed to by OFFSET. You must call `syms_init' (*note syms_init::.) before calling any of the other `syms_*' functions for the first time. This function is meant to be used to convert numerical addresses into function names and offsets into their code, like what `symify' does with the call frame traceback. The function ignores several dummy symbols, like `_end' and `_etext'. Return Value ------------ The name of the found symbol, or the printed hexadecimal representation of ADDR, if no symbol was found near ADDR. The return value is a pointer to a static buffer, so don't overwrite it and don't pass it to `free'! Portability ----------- not ANSI, not POSIX Example ------- unsigned long offs; char *symbol_name; syms_init ("foo.exe"); symbol_name = syms_val2name (0x1c12, &offs); printf ("The address %x is at %s%+ld\n", 0x1c12, symbol_name, offs); File: libc.info, Node: sync, Next: sys_errlist, Prev: syms_val2name, Up: Alphabetical List sync ==== Syntax ------ #include <unistd.h> int sync(void); Description ----------- Intended to assist porting Unix programs. Under Unix, `sync' flushes all caches of previously written data. In this implementation, `sync' calls `fsync' on every open file. *Note fsync::. It also calls `_flush_disk_cache' (*note _flush_disk_cache::.) to try to force cached data to the disk. Return Value ------------ Always returns 0. Portability ----------- not ANSI, not POSIX Example ------- sync(); File: libc.info, Node: sys_errlist, Next: sys_nerr, Prev: sync, Up: Alphabetical List sys_errlist =========== Syntax ------ #include <errno.h> extern char *sys_errlist[]; Description ----------- This array contains error messages, indexed by `errno', that describe the errors. Portability ----------- not ANSI, not POSIX Example ------- printf("Error: %s\n", sys_errlist[errno]); File: libc.info, Node: sys_nerr, Next: sysconf, Prev: sys_errlist, Up: Alphabetical List sys_nerr ======== Syntax ------ #include <errno.h> extern int sys_nerr; Description ----------- This variable gives the number of error messages in `sys_errlist' (*note sys_errlist::.). Portability ----------- not ANSI, not POSIX Example ------- if (errno < sys_nerr) printf("Error: %s\n", sys_errlist[errno]); File: libc.info, Node: sysconf, Next: system, Prev: sys_nerr, Up: Alphabetical List sysconf ======= Syntax ------ #include <unistd.h> long sysconf(int which); Description ----------- This function returns various system configuration values, based on WHICH: case _SC_ARG_MAX: return _go32_info_block.size_of_transfer_buffer; case _SC_CHILD_MAX: return CHILD_MAX; case _SC_CLK_TCK: return CLOCKS_PER_SEC; case _SC_NGROUPS_MAX: return NGROUPS_MAX; case _SC_OPEN_MAX: return 255; case _SC_JOB_CONTROL: return -1; case _SC_SAVED_IDS: return -1; case _SC_STREAM_MAX: return _POSIX_STREAM_MAX; case _SC_TZNAME_MAX: return TZNAME_MAX; case _SC_VERSION: return _POSIX_VERSION; Return Value ------------ The value. Portability ----------- not ANSI, POSIX File: libc.info, Node: system, Next: tan, Prev: sysconf, Up: Alphabetical List system ====== Syntax ------ #include <stdlib.h> int system(const char *cmd); Description ----------- This function runs the command or program specified by CMD. If CMD is a null pointer, `system' returns non-zero only if a shell is available. If CMD is an empty string, the command processor pointed to by `SHELL' or `COMSPEC' variables in the environment will be invoked interactively; type `exit <RET>' to return to the program which called `system'. (Note that some other DOS compilers treat a null pointer like an empty command line, contrary to ANSI C requirements.) When calling programs compiled by DJGPP this function will not use `COMMAND.COM' and so will not be subject to its 126 character limit on command lines. Command lines and pipes (i.e., the use of `<', `>', `>>', and `|') will be simulated internally in this function; this means that you can have both long command lines and redirection/pipes when running DJGPP programs with this function. By default, `COMMAND.COM' will only be invoked to run commands internal to it, or to run batch files (but this can be changed, see below). In these cases, the returned error code will always be zero, since `COMMAND.COM' always exits with code 0. Certain commands internal to `COMMAND.COM' that don't make sense or cause no effect in the context of `system' are ignored by this function. These are `REM', `EXIT', `GOTO', `SHIFT'; `SET', `PATH' and `PROMPT' are ignored only if called with an argument. You can disable this feature if you need, see below. Some commands are emulated internally by `system', because the emulation is better than the original. Currently, the only emulated command is `CD' or `CHDIR': the emulation knows about forward slashes and also switches the current drive. This emulation can also be switched off, as explained below. When `system' is presented with an internal shell command, it checks the environment variables `SHELL' and `COMSPEC' (in that order) and invokes the program that they point to. If the shell thus found is one of the DOS shells (`COMMAND.COM', `4DOS' or `NDOS'), they are called with the `/c' switch prepended to the command line. Otherwise, `system' assumes that the shell is a Unix-style shell and passes it the entire command line via a temporary file, invoking the shell with a single argument which is the name of that file. Shell scripts and batch files are invoked by calling either the program whose name appears on the first line (like in `#! /bin/sh'), or the default shell if none is specified by the script. If the name of the shell specified by the script is a Unix-style pathname, without a drive letter and with no extension, `system' will additionally search for it on the `PATH'. This allows to invoke Unix shell scripts unmodified, if you have a ported shell installed on your system. You can customize the behavior of `system' using a bit-mapped variable `__system_flags', defined on `<stdlib.h>'. The following bits are currently defined: `__system_redirect' When set (the default), specifies that `system' can use its internal redirection and pipe code. If reset, any command line that includes an unquoted redirection symbol will be passed to the shell. `__system_call_cmdproc' When set, `system' will always call the shell to execute the command line. If reset (the default), the shell will only be called when needed, as described above. You should *always* set this bit if you use a real, Unix-style shell (also, set `__system_use_shell', described below, and the `SHELL' environment variable). `__system_use_shell' When set (the default), the `SHELL' environment variable will take precedence upon `COMSPEC'; this allows you to specify a special shell for `system' that doesn't affect the rest of DOS. If reset, only `COMSPEC' is used to find the name of the command processor. `__system_allow_multiple_cmds' When set, you can put multiple commands together separated by the `;' character. If reset (the default), the command line passed to `system' is executed as a single command and `;' has no special meaning. `__system_allow_long_cmds' When set (the default), `system' will handle command lines longer than the DOS 126-character limit; this might crash your program in some cases, as the low-level functions that invoke the child program will only pass them the first 126 characters. When reset, `system' will detect early that the command line is longer than 126 characters and refuse to run it, but you will not be able to call DJGPP programs with long command lines. `__system_emulate_command' If reset (the default), `system' will pass the entire command line to the shell if its name is one of the following: `sh.exe', `sh16.exe', `sh32.exe', `bash.exe', `tcsh.exe'. When set, `system' will attempt to emulate redirection and pipes internally, even if `COMSPEC' or `SHELL' point to a Unix-style shell. `__system_handle_null_commands' When set (the default), commands internal to `COMMAND.COM' and compatible shells which have no effect in the context of `system', are ignored (the list of these commands was given above). If reset, these commands are processed as all others, which means `COMMAND.COM' will be called to execute them. Note that this bit shouldn't be used with a Unix-style shell, because it does the wrong thing then. With Unix-style shells, you are supposed to set the `__system_call_cmdproc' bit which will always call the shell. `__system_ignore_chdir' If set, the `CD' and `CHDIR' commands are ignored. When reset (the default), the processing of these commands depends on the `__system_emulate_chdir' bit, see below. This bit is for compatibility with Unix, where a single `cd dir' command has no effect, because the current working directory there is not a global notion (as on MSDOS). Don't set this bit if you use multiple commands (see `__system_allow_multiple_cmds' above). `__system_emulate_chdir' When set, the `CD' and `CHDIR' commands are emulated internally: they change the drive when the argument specifies a drive letter, and they support both forward slashes and backslashes in pathnames. When `CD' is called without an argument, it prints the current working directory with forward slashes and down-cases DOS 8+3 names. If this bit is reset (the default), `CD' and `CHDIR' are passed to the shell. The behavior of `system' can be customized at run time by defining the variable `DJSYSFLAGS' in the environment. The value of that variable should be the numerical value of `__system_flags' that you'd like to set; it will override the value of `__system_flags' specified when the program was compiled. Return Value ------------ If CMD is a null pointer, `system' returns non-zero if a shell is available. The actual test for the existence of an executable file pointed to by `SHELL' or `COMSPEC' is only performed if the shell is to be invoked to process the entire command line; if most of the work is to be done by `system' itself, passing a null pointer always yields a non-zero return value, since the internal emulation is always "available". Otherwise, the return value is the exit status of the child process in its lower 8 bits; bits 8-17 of the return value will hold `SIGINT' or `SIGABRT' if the child process was aborted by `Ctrl-C' or Critical Device Error, respectively; otherwise they will be zero(1). If the child couldn't be run, `system' will return -1 and set `errno' to an appropriate value. Note that if `COMMAND.COM' was used to run the child, it will always return a 0 status, even if the command didn't run successfully. However, `system' only calls `COMMAND.COM' when it needs to run commands internal to it. Portability ----------- ANSI, POSIX Example ------- system("cc1plus.exe @cc123456.gp"); ---------- Footnotes ---------- (1) Many DOS programs catch `Ctrl-C' keystrokes and Critical Errors, and handle them in customized ways. If this handling prevents DOS from realizing that the program was aborted due to these reasons, bits 8-17 of the value returned by `system' will most probably be zero. Don't count on these bits to hold the signal number! File: libc.info, Node: tan, Next: tanh, Prev: system, Up: Alphabetical List tan === Syntax ------ #include <math.h> double tan(double x); Description ----------- This function computes the tangent of X (which should be given in radians). Return Value ------------ The tangent of X. If the absolute value of X is finite but greater than or equal to 2^63, the return value is 0 (since for arguments that large each bit of the mantissa is more than `Pi'). If the value of X is infinite or `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: tanh, Next: tcdrain, Prev: tan, Up: Alphabetical List tanh ==== Syntax ------ #include <math.h> double tanh(double x); Description ----------- This function computes the hyperbolic tangent of X. Return Value ------------ The hyperbolic tangent of X. If X is either a positive or a negative infinity, the result is unity with the same sign as X, and `errno' is not changed. If X is `NaN', the return value is `NaN' and `errno' is set to `EDOM'. Portability ----------- ANSI, POSIX File: libc.info, Node: tcdrain, Next: tcflow, Prev: tanh, Up: Alphabetical List tcdrain ======= Syntax ------ #include <termios.h> int tcdrain (int fd); Description ----------- This function waits until all the output is written to the file/device referred to by the handle FD. In this implementation, this function does nothing except checking the validity of its arguments; it is provided for compatibility only. Note that the termios emulation handles console only. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX File: libc.info, Node: tcflow, Next: tcflush, Prev: tcdrain, Up: Alphabetical List tcflow ====== Syntax ------ #include <termios.h> int tcflow (int fd, int action); Description ----------- This function suspends transmission of data to, or reception of data from, the device/file open on handle FD. The ACTION argument can take one of these values: `TCOOFF' the output is suspended `TCOON' the output is resumed `TCIOFF' the STOP character is transmitted `TCION' the START character is transmitted The current START and STOP characters are stored in the `termios' structure that is currently in effect. *Note Termios functions::, for more details about that. Note that the DJGPP termios emulation handles console only. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX File: libc.info, Node: tcflush, Next: tcgetattr, Prev: tcflow, Up: Alphabetical List tcflush ======= Syntax ------ #include <termios.h> int tcflush (int fd, int which); Description ----------- This function clears the input and/or output queues on for the device/file open on handle FD. The WHICH argument can take these values: `TCIFLUSH' the unprocessed characters in the input buffer are discarded `TCOFLUSH' no effect (provided for compatibility) `TCIOFLUSH' has the combined effect of `TCIFLUSH' and `TCOFLUSH' Note that the termios emulation handles console only. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX File: libc.info, Node: tcgetattr, Next: tcgetpgrp, Prev: tcflush, Up: Alphabetical List tcgetattr ========= Syntax ------ #include <termios.h> int tcgetattr (int fd, struct termios *termiosp); Description ----------- This function gets the parameters associated with the file/device referred to by the handle FD and stores them in the termios structure TERMIOSP. *Note Termios functions::, for the full description of `struct termios' and its members. Note that the termios emulation handles console only. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX Example ------- struct termios termiosbuf; int rc = tcgetattr (0, &termiosbuf); File: libc.info, Node: tcgetpgrp, Next: tcsendbreak, Prev: tcgetattr, Up: Alphabetical List tcgetpgrp ========= Syntax ------ #include <termios.h> int tcgetpgrp (int fd); Description ----------- This function returns the value of the "process group ID" for the foreground process associated with the terminal. The file descriptor FD must be connected to the terminal, otherwise the function will fail. Return Value ------------ If FD is connected to the terminal, the function returns the process group ID, which is currently identical to the value returned by `getpgrp()' (*note getpgrp::.). Otherwise, it returns -1 and sets `errno' to `ENOTTY'. Portability ----------- not ANSI, POSIX File: libc.info, Node: tcsendbreak, Next: tcsetattr, Prev: tcgetpgrp, Up: Alphabetical List tcsendbreak =========== Syntax ------ #include <termios.h> int tcsendbreak (int fd, int duration); Description ----------- This function generates a break condition for `DURATION*0.25' seconds. In the current implementation this function does nothing; it is provided for compatibility only. Note that the termios emulation handles console only. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX File: libc.info, Node: tcsetattr, Next: tcsetpgrp, Prev: tcsendbreak, Up: Alphabetical List tcsetattr ========= Syntax ------ #include <termios.h> int tcsetattr (int fd, int action, const struct termios *termiosp); Description ----------- This function sets termios structure for device open on the handle FD from the structure TERMIOSP. Note that the termios emulation handles console only. The ACTION argument can accept the following values: `TCSANOW' `TCSADRAIN' `TCSAFLUSH' Currently, any of these values causes the values in TERMIOSP to take effect immediately. *Note Termios functions::, for the description of the `struct termios' structure. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX Example ------- tcsetattr (0, TCSANOW, &termiosbuf); File: libc.info, Node: tcsetpgrp, Next: tell, Prev: tcsetattr, Up: Alphabetical List tcsetpgrp ========= Syntax ------ #include <termios.h> int tcsetpgrp (int fd, pid_t pgroup_id); Description ----------- This function sets the foreground "process group ID" for the terminal connected to file descriptor FD. FD must be a valid handle connected to a terminal device, and PGROUP_ID must be the process group ID of the calling process, or the function will fail. Return Value ------------ If FD is a valid handle connected to a terminal and PGROUP_ID is equal to what `getpgrp()' returns (*note getpgrp::.), the function will do nothing and return zero. Otherwise, -1 will be returned and `errno' will be set to a suitable value. In particular, if the PGROUP_ID argument is different from what `getpgrp()' returns, `tcsetpgrp' sets `errno' to `ENOSYS'. Portability ----------- not ANSI, POSIX File: libc.info, Node: tell, Next: telldir, Prev: tcsetpgrp, Up: Alphabetical List tell ==== Syntax ------ #include <io.h> off_t tell(int file); Description ----------- This function returns the location of the file pointer for FILE. Return Value ------------ The file pointer, or -1 on error. Portability ----------- not ANSI, not POSIX Example ------- off_t q = tell(fd); File: libc.info, Node: telldir, Next: tempnam, Prev: tell, Up: Alphabetical List telldir ======= Syntax ------ #include <dirent.h> long telldir(DIR *dir); Description ----------- This function returns a value which indicates the position of the pointer in the given directory. This value is only useful as an argument to `seekdir' (*note seekdir::.). Return Value ------------ The directory pointer. Portability ----------- not ANSI, not POSIX Example ------- DIR *dir; long q = telldir(dir); do_something(); seekdir(dir, q); File: libc.info, Node: tempnam, Next: Termios functions, Prev: telldir, Up: Alphabetical List tempnam ======= Syntax ------ #include <stdio.h> char * tempnam(const char *tmpdir, const char *prefix); Description ----------- This function generates a file name which can be used for a temporary file, and makes sure that no other file by that name exists. The caller has control on the choice of the temporary file's directory, and the initial letters of the file's basename. If the argument TMPDIR points to the name of the directory in which the temporary file will be created, `tempnam' will ensure that the generate name is unique *in that directory*. If the argument PREFIX points to a string, then that string will be used as the first few characters of the file's basename. Due to limitations of the DOS 8.3 file namespace, only up to two first characters in PREFIX will be used. If TMPDIR is `NULL', or empty, or points to a non-existent directory, `tempnam' will use a default directory. The default directory is determined by testing, in sequence, the directories defined by the values of environment variables `TMPDIR', `TEMP' and `TMP'. The first variable that is found to point to an existing directory will be used. If none of these variables specify a valid directory, `tempnam' will use the static default path prefix defined by `P_tmpdir' on `<stdio.h>', or `"c:/"', in that order. If PREFIX is `NULL' or empty, `tempnam' will supply its own default prefix `"tm"'. `tempnam' puts the generated name into space allocated by `malloc'. It is up to the caller to free that space when it is no longer needed. Note that `tempnam' does not actually create the file, nor does it ensure in any way that the file will be automatically deleted when it's no longer used. It is the user's responsibility to do that. Return Value ------------ On success, `tempnam' returns a pointer to space (allocated with a call to `malloc') where the file name is constructed. If `malloc' failed to provide sufficient memory buffer, or if no valid directory to hold the file was found, `tempnam' returns a `NULL' pointer. Portability ----------- not ANSI, not POSIX Example ------- #include <stdio.h> tempnam ("c:/tmp/", "foo"); File: libc.info, Node: Termios functions, Next: textattr, Prev: tempnam, Up: Alphabetical List Termios functions ================= The `termios' functions allow to control terminals and asynchronous communications ports. The DJGPP implementation currently supports the `termios' functionality for console devices only. It does that by reading the keyboard via the BIOS Int 16h and writes to the screen via the direct output interrupt 29h. This I/O redirection is performed by the special hook internal to the library. Many of the `termios' functions accept a TERMIOSP argument which is a pointer to a `struct termios' variable. Here's the description of this structure: #define NCCS 12 struct termios { cc_t c_cc[NCCS]; /* control characters */ tcflag_t c_cflag; /* control modes */ tcflag_t c_iflag; /* input modes */ tcflag_t c_lflag; /* local modes */ tcflag_t c_oflag; /* output modes */ speed_t c_ispeed; /* input baudrate */ speed_t c_ospeed; /* output baudrate */ } The array `c_cc[]' defines the special control characters. the following table lists the supported control functions the default characters which invoke those functions, and the default values for MIN and TIME parameters: Index Name Function Default Value 1 VEOF Signal End-Of-Input Ctrl-D 2 VEOL Signal End-Of-Line [Disabled] 3 VERASE Delete previous character Backspace 4 VINTR Generate SIGINT Ctrl-C 5 VKILL Erase current line Ctrl-U 6 VMIN The MIN value 1 7 VQUIT Generate SIGQUIT Ctrl-\ 8 VSTART Resume output Ctrl-Q 9 VSTOP Suspend output Ctrl-S 10 VSUSP Suspend program Ctrl-Z 11 VTIME TIME value 0 The special characters (like `VEOL', `VKILL', etc.) produce their effect only under the "canonical input processing", that is, when the `ICANON' bit in the `c_lflag' member of `struct termios' (see below) is set. If `ICANON' is *not* set, all characters are processed as regular characters and returned to the caller; only the `VMIN' and `VTIME' parameters are meaningful in the "non-canonical processing" mode. The `VEOL' character can be used to signal end of line (and thus end of input in the canonical mode) in addition to the normal `RET' key. In the non-canonical mode, input ends as soon as at least `VMIN' characters are received. Note that the values of `VMIN' and `VTIME' are currently ignored; `termios' functions always work as if `VMIN' were 1 and `VTIME' were zero. Other parameters are supported (for console devices only), except that VSTOP and VSTART characters are not inserted to the input, but otherwise produce no effect. The `c_cflag' member of `struct termios' describes the hardware terminal control, as follows: Symbol Function B0 Hang up B50 50 baud B75 75 baud B110 110 baud B134 134.5 baud B150 150 baud B200 200 baud B300 300 baud B600 600 baud B1200 1200 baud B1800 1800 baud B2400 2400 baud B4800 4800 baud B9600 9600 baud B19200 19200 baud B38400 38400 baud CSIZE Character size: CS5 5-bit characters CS6 6-bit characters CS7 7-bit characters CS8 8-bit characters CSTOPB If set, send two stop bits CREAD Enable reading PARENB Enable parity PARODD If set, use odd parity HUPCL Hang up on last close CLOCAL If set, line is local Note that since the DOS terminal doesn't use asynchronous ports, the above parameters are always ignored by the implementation. The default value of `c_cflag' is `(CS8|CREAD|CLOCAL)'. The `c_lflag' member of `struct termios' defines the local modes that control the terminal functions: Symbol Function ISIG If set, enable signals SIGINT and SIGQUIT ICANON If set, enable canonical input processing ECHO If set, enable echoing ECHOE Erase character deletes ECHOK Output newline after the kill character ECHONL Echo the newline NOFLSH [Ignored] TOSTOP [Ignored] ECHOCTL Echo control characters as ^X ECHOKE Erase killed line IEXTEN [Ignored] The default value of `c_lflag' is `(ISIG|ICANON|ECHO|IEXTEN|ECHOE|ECHOKE|ECHOCTL)'. The `c_iflag' member of `struct termios' describes the input control: Symbol Function IGNBRK Ignore Ctrl-BREAK BRKINT Generate SIGINT on Ctrl-BREAK IGNPAR [Ignored] PARMRK [Ignored] INPCK [Ignored] ISTRIP Strip the 8th bit from input INLCR Map NL to CR on input IGNCR Ignore CR characters ICRNL Map CR to NL on input IXON [Ignored] IXOFF Enable start/stop input control IMAXBEL Ring the bell if input line too long The default value of `c_iflag' is `(BRKINT|ICRNL|IMAXBEL)'. The `c_oflag' member of `struct termios' specifies the output handling: Symbol Function OPOST If not set, output characters verbatim ONLCR Map newline to CR-LF pair on output OCRNL Map CR to NL on output ONOEOT Don't output EOT characters Note that if the `OPOST' bit is not set, all the other flags are ignored and the characters are output verbatim. The default value of `c_oflag' is `(OPOST|ONLCR|ONOEOT)'. The `c_ispeed' and `c_ospeed' members specify, respectively, the input and output baudrate of the terminal. They are set by default to 9600 baud, but the value is always ignored by this implementation, since no asynchronous ports are used. File: libc.info, Node: textattr, Next: textbackground, Prev: Termios functions, Up: Alphabetical List textattr ======== Syntax ------ #include <conio.h> void textattr(int _attr); Description ----------- Sets the attribute used for future writes to the screen: ---- XXXX = foreground color -XXX ---- = background color X--- ---- = 1=blink 0=steady The include file <conio.h> contains an enum COLORS that define the various values that can be used for these bitfields; light colors can only be used for the foreground. Portability ----------- not ANSI, not POSIX Example ------- /* blinking white on blue */ textattr(BLINK | (BLUE << 4) | WHITE); File: libc.info, Node: textbackground, Next: textcolor, Prev: textattr, Up: Alphabetical List textbackground ============== Syntax ------ #include <conio.h> void textbackground(int _color); Description ----------- Sets just the background of the text attribute. *Note textattr::. Portability ----------- not ANSI, not POSIX File: libc.info, Node: textcolor, Next: textmode, Prev: textbackground, Up: Alphabetical List textcolor ========= Syntax ------ #include <conio.h> void textcolor(int _color); Description ----------- Sets just the foreground of the text attribute. *Note textattr::. Portability ----------- not ANSI, not POSIX File: libc.info, Node: textmode, Next: time, Prev: textcolor, Up: Alphabetical List textmode ======== Syntax ------ #include <conio.h> void textmode(int _mode); Description ----------- Sets the text mode of the screen. _MODE is one of the following: `LASTMODE' The text mode which was in effect *before* the last call to `textmode()'. `BW40' 40-column black and white (on a color screen) `C40' 40-color color. `BW80' 80-column black and white (on a color screen) `C80' 80-column color `MONO' The monochrome monitor `C4350' 80-column, 43- (on EGAs) or 50-row (on VGAs) color *Note _set_screen_lines::, for a more versatile method of setting text screen dimensions. Portability ----------- not ANSI, not POSIX File: libc.info, Node: time, Next: times, Prev: textmode, Up: Alphabetical List time ==== Syntax ------ #include <time.h> time_t time(time_t *t); Description ----------- If T is not `NULL', the current time is stored in `*t'. Return Value ------------ The current time is returned. Portability ----------- ANSI, POSIX Example ------- printf("Time is %d\n", time(0)); File: libc.info, Node: times, Next: tmpfile, Prev: time, Up: Alphabetical List times ===== Syntax ------ #include <sys/times.h> clock_t times(struct tms *buf); Description ----------- This function returns the number of clock ticks used by the current process and all of its children until the moment of call. The number of tics per second is `CLOCKS_PER_SEC', defined on time.h. This is the structure in which `times' returns its info: struct tms { clock_t tms_cstime; clock_t tms_cutime; clock_t tms_stime; clock_t tms_utime; }; Currently, the elapsed time of the running program is returned in the `tms_utime' field, and all other fields return as zero. Return Value ------------ The number of elapsed tics since the program started. Portability ----------- not ANSI, POSIX Example ------- printf("We used %d seconds of elapsed time\n", times(&buf)/CLOCKS_PER_SEC); File: libc.info, Node: tmpfile, Next: tmpnam, Prev: times, Up: Alphabetical List tmpfile ======= Syntax ------ #include <stdio.h> FILE *tmpfile(void); Description ----------- This function opens a temporary file. It will automatically be removed if the file is closed or when the program exits. The name of the file is generated by the same algorithm as described under tmpnam() (*note tmpnam::.). Return Value ------------ A newly opened file. Portability ----------- ANSI, POSIX Example ------- FILE *tmp = tmpfile(); File: libc.info, Node: tmpnam, Next: toascii, Prev: tmpfile, Up: Alphabetical List tmpnam ====== Syntax ------ #include <stdio.h> char *tmpnam(char *s); Description ----------- This functions generates a string that is a valid file name and that is not the same as the name of an existing file. A different string is guaranteed to be produced each time it is called, up to `TMP_MAX' times (`TMP_MAX' is defined on stdio.h). If `tmpnam' is called more than TMP_MAX times, the behavior is implementation-dependent (ours just wraps around and tries to reuse the same file names from the beginning). This function examines the environment to determine the directory in which the temporary file will be opened. It looks for one of the variables `"TMPDIR"', `"TEMP"' and `"TMP"', in that order. The first one which is found in the environment will be used on the assumption that it points to a directory. If neither of the above variables is defined, `tmpnam' defaults to the "c:/" directory (which under MS-DOS might mean that it fails to generate TMP_MAX unique names, because DOS root directories cannot grow beyond certain limits). Return Value ------------ If S is a null pointer, `tmpnam' leaves its result in an internal static buffer and returns a pointer to that buffer. If S is not a null pointer, it is assumed to point to an array of at least `L_tmpnam' characters, and `tmpnam' writes its result in that array and returns a pointer to it as its value. Portability ----------- ANSI, POSIX Example ------- char buf[L_tmpnam]; char *s = tmpnam(buf); File: libc.info, Node: toascii, Next: tolower, Prev: tmpnam, Up: Alphabetical List toascii ======= Syntax ------ #include <ctype.h> int toascii(int c); Description ----------- This function strips the high bit of C, forcing it to be an ASCII character. Return Value ------------ The ASCII character. Portability ----------- not ANSI, not POSIX Example ------- for (i=0; buf[i]; i++) buf[i] = toascii(buf[i]); File: libc.info, Node: tolower, Next: toupper, Prev: toascii, Up: Alphabetical List tolower ======= Syntax ------ #include <ctype.h> int tolower(int c); Description ----------- This function returns C, converting it to lower case if it is upper case. *Note toupper::. Return Value ------------ The lower case letter. Portability ----------- ANSI, POSIX Example ------- for (i=0; buf[i]; i++) buf[i] = tolower(buf[i]); File: libc.info, Node: toupper, Next: _truename, Prev: tolower, Up: Alphabetical List toupper ======= Syntax ------ #include <ctype.h> int toupper(int c); Description ----------- This function returns C, converting it to upper case if it is lower case. *Note tolower::. Return Value ------------ The upper case letter. Portability ----------- ANSI, POSIX Example ------- for (i=0; buf[i]; i++) buf[i] = toupper(buf[i]); File: libc.info, Node: _truename, Next: truncate, Prev: toupper, Up: Alphabetical List _truename ========= Syntax ------ #include <sys/stat.h> char * _truename(const char *path, char *true_path); Description ----------- Given a PATH of a file, returns in TRUE_PATH its canonicalized pathname, with all letters uppercased, default drive and directory made explicit, forward slashes converted to backslashes, asterisks converted to appropriate number of of question marks, file and directory names truncated to 8.3 if necessary, "." and ".." resolved, extra slashes (but the last, if present) removed, SUBSTed, JOINed and ASSIGNed drives resolved. Character devices return as "X:/DEVNAME" (note the forward slash!), where X is the CURRENT drive and DEVNAME is the device name (e.g. CON). This is exactly what DOS TRUENAME command does. See Ralph Brown's Interrupt List for more details. The named PATH doesn't have to exist, but the drive, if given as part of it, should be a legal DOS drive, as this function hits the disk. The function will fail if given a PATH which (1) is an empty string; or (2) contains only the drive letter (e.g. "c:"); or (3) has leading whitespace. It will also fail if it couldn't allocate memory required for its communication with DOS or for TRUE_PATH (see below). Upon success, the function will place the result in TRUE_PATH, if that's non-NULL; the buffer should be large enough to contain the largest possible pathname (PATH_MAX characters). If TRUE_PATH is a NULL pointer, the space to hold the result will be allocated by calling *Note malloc::; it is up to the caller to release the buffer by calling *Note free::. Return Value ------------ The function returns the pointer to the result. In case of any failure, a NULL pointer is returned, and ERRNO is set. Portability ----------- not ANSI, not POSIX Example ------- fprintf(stderr, "True name of %s is %s\n", path, _truename(path, (char *)0)); File: libc.info, Node: truncate, Next: ttyname, Prev: _truename, Up: Alphabetical List truncate ======== Syntax ------ #include <unistd.h> int truncate(const char *file, off_t size); Description ----------- This function truncates FILE to SIZE bytes. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- truncate("/tmp/data.txt", 400); File: libc.info, Node: ttyname, Next: tzset, Prev: truncate, Up: Alphabetical List ttyname ======= Syntax ------ #include <unistd.h> char *ttyname(int file); Description ----------- Gives the name of the terminal associated with FILE. Return Value ------------ Returns "con" if FILE is a device, else `NULL'. Portability ----------- not ANSI, POSIX Example ------- char *tty = ttyname(0); File: libc.info, Node: tzset, Next: tzsetwall, Prev: ttyname, Up: Alphabetical List tzset ===== Syntax ------ #include <time.h> extern char *tzname[2]; void tzset(void); Description ----------- This function initializes the global variable `tzname' according to environment variable `TZ'. After the call, `tzname' holds the specifications for the time zone for the standard and daylight-saving times. Return Value ------------ None. Portability ----------- not ANSI, POSIX File: libc.info, Node: tzsetwall, Next: uclock, Prev: tzset, Up: Alphabetical List tzsetwall ========= Syntax ------ #include <time.h> void tzsetwall(void); Description ----------- This function sets up the time conversion information used by `localtime' (*note localtime::.) so that `localtime' returns the best available approximation of the local wall clock time. Return Value ------------ None. Portability ----------- not ANSI, not POSIX File: libc.info, Node: uclock, Next: umask, Prev: tzsetwall, Up: Alphabetical List uclock ====== Syntax ------ #include <time.h> uclock_t uclock(void); Description ----------- This function returns the number of uclock ticks since an arbitrary time, actually, since the first call to `uclock', which itself returns zero. The number of tics per second is `UCLOCKS_PER_SEC' (declared in the `time.h' header file. `uclock' is provided for very high-resulution timing. It is currently accurate to better than 1 microsecond (actually about 840 nanoseconds). You cannot time across two midnights with this implementation, giving a maximum useful period of 48 hours and an effective limit of 24 hours. Casting to a 32-bit integer limits its usefulness to about an hour before 32 bits will wrap. Note that `printf' will only print a value of type `uclock_t' correctly if you use format specifiers for `long long' data, such as `%Ld' or `%lld', because `uclock_t' is a 64-bit integer. *Note printf::. Also note that `uclock' reprograms the interval timer in your PC to act as a rate generator rather than a square wave generator. I've had no problems running in this mode all the time, but if you notice strange things happening with the clock (losing time) after using `uclock', check to see if this is the cause of the problem. Windows 3.X doesn't allow to reprogram the timer, so the values returned by `uclock' there are incorrect. DOS and Windows 9X don't have this problem. Return Value ------------ The number of tics. Portability ----------- not ANSI, not POSIX Example ------- printf("%Ld seconds have elapsed\n", (long long)(uclock()/UCLOCKS_PER_SEC)); File: libc.info, Node: umask, Next: uname, Prev: uclock, Up: Alphabetical List umask ===== Syntax ------ #include <sys/stat.h> mode_t umask(mode_t cmask); Description ----------- This function does nothing. It exists to assist porting. Portability ----------- not ANSI, POSIX File: libc.info, Node: uname, Next: ungetc, Prev: umask, Up: Alphabetical List uname ===== Syntax ------ #include <sys/utsname.h> #int uname(struct utsname *u); Description ----------- Fills in the structure with information about the system. struct utsname { char machine[9]; char nodename[32]; char release[9]; char sysname[9]; char version[9]; }; `machine' "pc" `nodename' The name of your PC (if networking is installed), else "pc". `release' The minor release of dos. For example, dos 1.23 would return "23" here. `sysname' The flavor of the OS. `version' The major release of dos. For example, dos 1.23 would return "1" here. Return Value ------------ Zero on success, else nonzero. Portability ----------- not ANSI, POSIX File: libc.info, Node: ungetc, Next: ungetch, Prev: uname, Up: Alphabetical List ungetc ====== Syntax ------ #include <stdio.h> int ungetc(int c, FILE *file); Description ----------- This function pushes C back into the FILE. You can only push back one character at a time. Return Value ------------ The pushed-back character, or `EOF' on error. Portability ----------- ANSI, POSIX Example ------- int q; while (q = getc(stdin) != 'q'); ungetc(q); File: libc.info, Node: ungetch, Next: unlink, Prev: ungetc, Up: Alphabetical List ungetch ======= Syntax ------ #include <conio.h> int ungetch(int); Description ----------- Puts a character back, so that *Note getch:: will return it instead of actually reading the console. Return Value ------------ The charater is returned. Portability ----------- not ANSI, not POSIX File: libc.info, Node: unlink, Next: unlock, Prev: ungetch, Up: Alphabetical List unlink ====== Syntax ------ #include <unistd.h> int unlink(const char *file); Description ----------- This function removes a file from the file system. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, POSIX Example ------- unlink("data.txt"); File: libc.info, Node: unlock, Next: _use_lfn, Prev: unlink, Up: Alphabetical List unlock ====== Syntax ------ #include <io.h> int unlock(int fd, long offset, long length); Description ----------- Unlocks a region previously locked by `lock'. *Note lock::. Return Value ------------ Zero if successful, nonzero if not. Portability ----------- not ANSI, not POSIX File: libc.info, Node: _use_lfn, Next: usleep, Prev: unlock, Up: Alphabetical List _use_lfn ======== Syntax ------ #include <fcntl.h> char _use_lfn(const char *path); Description ----------- The `_use_lfn' function returns a nonzero value if the low level libc routines will use the "Long File Name" (LFN) functions provided with Windows 9x (and other advanced filesystems), when accessing files and directories on the same filesystem as PATH. PATH may be any legal pathname; however, the function only needs the name of the root directory on the particular drive in question. If PATH is a `NULL' pointer, the function assumes that all the filesystems support (or do not support) LFN in the same manner, and returns the info pertinent to the last filesystem that was queried; this usually makes the call faster. Note that on Windows 95 you don't need to distinguish between different drives: they all support LFN API. If PATH does not specify the drive explicitly, the current drive is used. The header `fcntl.h' defines a macro `_USE_LFN'; applications should use this macro instead of calling `_use_lfn' directly. That is so this routine could be replaced with one which always returns 0 to disable using long file names. Calling `_USE_LFN' also makes the code more portable to other operating systems, where the macro can be redefined to whatever is appropriate for that environment (e.g., it should be a constant 1 on Unix systems and constant 0 for environments that don't support LFN API, like some other MSDOS compilers). Currently, `_USE_LFN' assumes that LFN API does *not* depend on a drive. Long file names can also be disabled by setting the flag `_CRT0_FLAG_NO_LFN' in `_crt0_startup_flags' for an image which should not allow use of long file names. Long names can be suppressed at runtime on a global basis by setting the environment variable `LFN' to `N', i.e. `SET LFN=N'. This might be needed if a distribution expected the truncation of long file names to 8.3 format to work. For example, if a C source routine included the file exception.h (9 letters) and the file was unzipped as exceptio.h, then GCC would not find the file unless you set `LFN=n'. The environment variable can be set in the `DJGPP.ENV' file to always disable LFN support on any system, or can be set in the DOS environment for a short term (single project) basis. If you dual boot a system between Windows 95 and DOS, you probably should set `LFN=n' in your `DJGPP.ENV' file, since long file names would not be visible under DOS, and working with the short names under DOS will damage the long names when returning to Windows 95. Return Value ------------ If LFN APIs are supported and should be used, it returns 1, else 0. Note that if the `_CRT0_FLAG_NO_LFN' bit is set, or `LFN' is set to `N' or `n' in the environment, both `_use_lfn' and `_USE_LFN' will always return 0 without querying the filesystem. You can reset the `_CRT0_FLAG_NO_LFN' bit at runtime to force filesystem to be queried. Portability ----------- not ANSI, not POSIX Example ------- #include <fcntl.h> #include <sys/stat.h> int fd = creat (_USE_LFN ? "MyCurrentJobFile.Text" : "currjob.txt", S_IRUSR | S_IWUSR); File: libc.info, Node: usleep, Next: utime, Prev: _use_lfn, Up: Alphabetical List usleep ====== Syntax ------ #include <unistd.h> unsigned usleep(unsigned usec); Description ----------- This function pauses the program for USEC microseconds. Note that, since `usleep' calls `clock' internally, and the latter has a 55-msec granularity, any argument less than 55msec will result in a pause of random length between 0 and 55 msec. Any argument less than 11msec (more precisely, less than 11264 microseconds), will always result in zero-length pause (because `clock' multiplies the timer count by 5). *Note clock::. Return Value ------------ The number of unslept microseconds (i.e. zero). Portability ----------- not ANSI, not POSIX Example ------- usleep(500000); File: libc.info, Node: utime, Next: utimes, Prev: usleep, Up: Alphabetical List utime ===== Syntax ------ #include <utime.h> int utime(const char *file, const struct utimbuf *time); Description ----------- This function sets the modification timestamp on the FILE. The new time is stored in this structure: struct utimbuf { time_t actime; /* access time (unused on FAT filesystems) */ time_t modtime; /* modification time */ }; Note that, as under DOS a file only has a single timestamp, the `actime' field of `struct utimbuf' is ignored by this function, and only `modtime' field is used. On filesystems which support long filenames, both fields are used and both access and modification times are set. Return Value ------------ Zero for success, nonzero for failure. Portability ----------- not ANSI, POSIX Example ------- struct utimbuf t; t.modtime = time(0); utime("data.txt", &t); File: libc.info, Node: utimes, Next: v2loadimage, Prev: utime, Up: Alphabetical List utimes ====== Syntax ------ #include <sys/time.h> int utimes(const char *file, struct timeval tvp[2]); Description ----------- This function sets the file access time as specified by `TVP[0]', and its modification time as specified by `TVP[1]'. `struct timeval' is defined as follows: struct timeval { time_t tv_sec; long tv_usec; }; Note that DOS and Windows maintain the file times with 2-second granularity. Therefore, the `tv_usec' member of the argument is always ignored, and the underlying filesystem truncates (or sometimes rounds) the actual file time stamp to the multiple of 2 seconds. On plain DOS, only one file time is maintained, which is arbitrarily taken from `TVP[1].tv_sec'. On Windows 9X, both times are used, but note that most versions of Windows only use the date part and ignore the time. Due to limitations of DOS and Windows, you cannot set times of directories. Return Value ------------ Zero on success, nonzero on failure. Portability ----------- not ANSI, not POSIX Example ------- time_t now; struct timeval tvp[2]; time(&now); tvp[1].tv_sec = now + 100; utimes("foo.dat", tvp); File: libc.info, Node: v2loadimage, Next: varargs, Prev: utimes, Up: Alphabetical List v2loadimage =========== Syntax ------ #include <debug/v2load.h> int v2loadimage (const char *program, const char *cmdline, jmp_buf load_state); Description ----------- This function loads an executable image of a DJGPP v2.x program and prepares it for debugging. PROGRAM should point to the file name of the executable program. `v2loadimage' does *not* search the `PATH' and does *not* try any executable extensions, so PROGRAM should point to a fully-qualified path, complete with the drive, directory, and file-name extension; otherwise the call will fail. CMDLINE should point to the command-line arguments to be passed to the program. The format of the command line should be exactly like the command tail DOS passes to programs: the first byte gives the length of the command tail, the tail itself begins with the second byte, and the tail is terminated by a CR character (decimal code 13); the length byte does not include the CR. The command-line arguments should look as if they were to be passed to the library function `system'. In particular, all special characters like wildcards and whitespace should be quoted as if they were typed at the DOS prompt. Note that currently, this function doesn't support command lines longer than the DOS 126-character limit. After the function loads the image and sets up the necessary memory segments for it to be able to run, it sets LOAD_STATE so that it can be used to `longjmp' to the debuggee's entry point. This information is typically used by `run_child' (*note run_child::.). Return Value ------------ Zero in case of success, non-zero otherwise. Portability ----------- not ANSI, not POSIX Example ------- cmdline = (char *) alloca (strlen (args) + 4); cmdline[0] = strlen (args); strcpy (cmdline + 1, args); cmdline[strlen (args) + 1] = 13; if (v2loadimage (exec_file, cmdline, start_state)) { printf ("Load failed for image %s\n", exec_file); exit (1); } edi_init (start_state); File: libc.info, Node: varargs, Next: vfork, Prev: v2loadimage, Up: Alphabetical List varargs ======= Syntax ------ #include <stdarg.h> void va_start(va_list ap, LAST_REQUIRED_ARG); TYPE va_arg(va_list ap, TYPE); void va_end(va_list ap); Description ----------- Used to write functions taking a variable number of arguments. Note that these are actually macros, and not functions. You must prototype the function with `...' in its argument list. Then, you do the following: * Create a variable of type `va_list'. * Initialize it by calling `va_start' with it and the name of the last required (i.e. non-variable) argument. * Retrieve the arguments by calling `va_arg' with the `va_list' variable and the type of the argument. As another alternative, you can pass the `va_list' to another function, which may then use `va_arg' to get at the arguments. `vprintf' is an example of this. * Call `va_end' to destroy the `va_list'. Be aware that your function must have some way to determine the number and types of the arguments. Usually this comes from one of the required arguments. Some popular ways are to pass a count, or to pass some special value (like `NULL') at the end. Also, the variable arguments will be promoted according to standard C promotion rules. Arguments of type `char' and `short' will be promoted to `int', and you should retrieve them as such. Those of type `float' will be promoted to `double'. Return Value ------------ `va_arg' returns the argument it fetched, the other macros return nothing. Portability ----------- ANSI, POSIX Example ------- int find_the_sum(int count, ...) { va_list ap; int i; int total = 0; va_start(ap, count); for (i = 0; i < count; i++) total += va_arg(ap, int); va_end(ap); return total; } int other_function(void) { return find_the_sum(6, 1, 2, 3, 4, 5, 6); } File: libc.info, Node: vfork, Next: vfprintf, Prev: varargs, Up: Alphabetical List vfork ===== Syntax ------ #include <unistd.h> pid_t vfork(void); Description ----------- This function always returns -1 and sets `errno' to ENOMEM, as MS-DOS does not support multiple processes. It exists only to assist in porting Unix programs. Portability ----------- not ANSI, not POSIX File: libc.info, Node: vfprintf, Next: vfscanf, Prev: vfork, Up: Alphabetical List vfprintf ======== Syntax ------ #include <stdio.h> #include <stdarg.h> int vfprintf(FILE *file, const char *format, va_list arguments); Description ----------- Sends formatted output from the ARGUMENTS to the FILE. *Note printf::. Return Value ------------ The number of characters written. Portability ----------- ANSI, POSIX Example ------- void my_errmsg(char *format, ...) { va_list arg; va_start(arg, format); fprintf(stderr, "my_errmsg: "); vfprintf(stderr, format, arg); va_end(arg); } File: libc.info, Node: vfscanf, Next: vprintf, Prev: vfprintf, Up: Alphabetical List vfscanf ======= Syntax ------ #include <stdio.h> int vfscanf(FILE *file, const char *format, va_list arguments); Description ----------- This function scans formatted text from FILE and stores it in the variables pointed to by the ARGUMENTS. *Note scanf::. Return Value ------------ The number of items successfully scanned. Portability ----------- not ANSI, not POSIX File: libc.info, Node: vprintf, Next: vscanf, Prev: vfscanf, Up: Alphabetical List vprintf ======= Syntax ------ #include <stdio.h> #include <stdarg.h> int vprintf(const char *format, va_list arguments); Description ----------- Sends formatted output from the ARGUMENTS to `stdout'. *Note printf::. *Note vfprintf::. Return Value ------------ The number of characters written. Portability ----------- ANSI, POSIX File: libc.info, Node: vscanf, Next: vsprintf, Prev: vprintf, Up: Alphabetical List vscanf ====== Syntax ------ #include <stdio.h> int vscanf(const char *format, va_list arguments); Description ----------- This function scans formatted text from `stdin' and stores it in the variables pointed to by the ARGUMENTS. *Note scanf::. *Note vfscanf::. Return Value ------------ The number of items successfully scanned. Portability ----------- not ANSI, not POSIX File: libc.info, Node: vsprintf, Next: vsscanf, Prev: vscanf, Up: Alphabetical List vsprintf ======== Syntax ------ #include <stdio.h> #include <stdarg.h> int vsprintf(char *buffer, const char *format, va_list arguments); Description ----------- Sends formatted output from the ARGUMENTS to the BUFFER. *Note printf::. *Note vfprintf::. Return Value ------------ The number of characters written. Portability ----------- ANSI, POSIX File: libc.info, Node: vsscanf, Next: wait, Prev: vsprintf, Up: Alphabetical List vsscanf ======= Syntax ------ #include <stdio.h> int vsscanf(const char *string, const char *format, va_list arguments); Description ----------- This function scans formatted text from the STRING and stores it in the variables pointed to by the ARGUMENTS. *Note scanf::. *Note vfscanf::. Return Value ------------ The number of items successfully scanned. Portability ----------- not ANSI, not POSIX File: libc.info, Node: wait, Next: waitpid, Prev: vsscanf, Up: Alphabetical List wait ==== Syntax ------ #include <sys/wait.h> pid_t pid = wait(int *status); Description ----------- This function causes its caller to delay its execution until a signal is received or one of its child processes terminates. If any child has terminated, return is immediate, returning the process ID and its exit status, if that's available. If no children processes were called since the last call, then -1 is returned and `errno' is set. Return Value ------------ If successful, this function returns the exit status of the child. If there is an error, these functions return -1 and set `errno' to indicate the error type. Bugs ---- Currently, this function always fails. Portability ----------- not ANSI, POSIX File: libc.info, Node: waitpid, Next: wcstombs, Prev: wait, Up: Alphabetical List waitpid ======= Syntax ------ #include <sys/wait.h> pid_t pid = waitpid((pid_t pid, int *status, int options); Description ----------- Currently, this function always fails. A -1 is returned and `errno' is set to indicate there are no children. Return Value ------------ If successful, this function returns the exit status of the child. If there is an error, these functions return -1 and set `errno' to indicate the error type. Bugs ---- Currently, this function always fails. Portability ----------- not ANSI, POSIX File: libc.info, Node: wcstombs, Next: wctomb, Prev: waitpid, Up: Alphabetical List wcstombs ======== Syntax ------ #include <stdlib.h> size_t wcstombs(char *s, const wchar_t *wcs, size_t n); Description ----------- Converts a wide character string to a multibyte string. At most N characters are stored. Return Value ------------ The number of characters stored. Portability ----------- ANSI, POSIX Example ------- int len = wcstombs(buf, wstring, sizeof(buf)); File: libc.info, Node: wctomb, Next: wherex, Prev: wcstombs, Up: Alphabetical List wctomb ====== Syntax ------ #include <stdlib.h> int wctomb(char *s, wchar_t wchar); Description ----------- Convert a wide character to a multibyte character. The string S must be at least `MB_LEN_MAX' bytes long. Return Value ------------ The number of characters stored. Portability ----------- ANSI, POSIX Example ------- char s[MB_LEN_MAX]; int mlen = wctomb(s, wc); File: libc.info, Node: wherex, Next: wherey, Prev: wctomb, Up: Alphabetical List wherex ====== Syntax ------ #include <conio.h> int wherex(void); Return Value ------------ The column the cursor is on. The leftmost column is 1. Portability ----------- not ANSI, not POSIX File: libc.info, Node: wherey, Next: wild, Prev: wherex, Up: Alphabetical List wherey ====== Syntax ------ #include <conio.h> int wherey(void); Return Value ------------ The row the cursor is on. The topmost row is 1. Portability ----------- not ANSI, not POSIX File: libc.info, Node: wild, Next: window, Prev: wherey, Up: Alphabetical List wild ==== Syntax ------ #include <debug/wild.h> int wild (char *pattern, char *string); Description ----------- This function matches a string pointed to by STRING against a pattern pointed to by PATTERN. PATTERN may include wildcard characters `?' and `*', meaning, respectively, any single character and any string of characters. The function returns non-zero if the string matches the pattern, zero otherwise. This functions is meant to be used for simple matching of patterns, such as if a debugger needs to allow specification of symbols using wildcards. Return Value ------------ The function returns non-zero if the string matches the pattern, zero otherwise. Portability ----------- not ANSI, not POSIX File: libc.info, Node: window, Next: write, Prev: wild, Up: Alphabetical List window ====== Syntax ------ #include <conio.h> void window(int _left, int _top, int _right, int _bottom); Description ----------- Specifies the window on the screen to be used for future output requests. The upper left corner of the physical screen is (1,1). Portability ----------- not ANSI, not POSIX File: libc.info, Node: write, Next: _write, Prev: window, Up: Alphabetical List write ===== Syntax ------ #include <unistd.h> int write(int file, const void *buffer, size_t count); Description ----------- This function writes COUNT bytes from BUFFER to FILE. It returns the number of bytes actually written. It will return zero or a number less than COUNT if the disk is full, and may return less than COUNT even under valid conditions. Note that if FILE is a text file, `write' may write more bytes than it reports. If COUNT is zero, the function does nothing and returns zero. Use `_write' if you want to actually ask dos to write zero bytes. The precise behavior of `write' when the target filesystem is full are somewhat troublesome, because DOS doesn't fail the underlying system call. If your application needs to rely on `errno' being set to `ENOSPC' in such cases, you need to invoke `write' as shown in the example below. In a nutshell, the trick is to call `write' one more time after it returns a value smaller than the COUNT parameter; then it will *always* set `errno' if the disk is full. Return Value ------------ The number of bytes written, zero at EOF, or -1 on error. Portability ----------- not ANSI, POSIX Example ------- This example shows how to call `write' in a way which ensures that `errno' will be set to `ENOSPC' if the target filesystem is or becomes full: char *buf_ptr; /* the buffer to write */ size_t buf_len; /* the number of bytes to write */ int desc; /* the file descriptor to write to */ while (buf_len > 0) { int written = write (desc, buf_ptr, buf_len); if (written <= 0) break; buf_ptr += written; buf_len -= written; } File: libc.info, Node: _write, Next: write_child, Prev: write, Up: Alphabetical List _write ====== Syntax ------ #include <io.h> ssize_t _write(int fildes, void *buf, size_t nbyte); Description ----------- This is a direct connection to the MS-DOS write function call, int 0x21, %ah = 0x40. No conversion is done on the data; it is written as raw binary data. This function can be hooked by the File-system extensions, see *Note File System Extensions::. If you don't want this, you should use `_dos_write' instead, see *Note _dos_write::. Return Value ------------ The number of bytes written, or -1 (and `errno' set) in case of failure. Note that DOS doesn't return an error indication when the target disk is full; therefore if the disk fills up while the data is written, `_write' does *not* return -1, it returns the number of bytes it succeeded to write. If you need to detect the disk full condition reliably, call `_write' again to try to write the rest of the data. This will cause DOS to return zero as the number of written bytes, and *then* `_write' will return -1 and set `errno' to `ENOSPC'. The example below shows one way of doing this. Portability ----------- not ANSI, not POSIX Example ------- This example shows how to call `_write' in a way which ensures that `errno' will be set to `ENOSPC' if the target filesystem is or becomes full: char *buf_ptr; /* the buffer to write */ size_t buf_len; /* the number of bytes to write */ int desc; /* the file descriptor to write to */ while (buf_len > 0) { int written = _write (desc, buf_ptr, buf_len); if (written <= 0) break; buf_ptr += written; buf_len -= written; } File: libc.info, Node: write_child, Next: write_sel_addr, Prev: _write, Up: Alphabetical List write_child =========== Syntax ------ #include <debug/dbgcom.h> void write_child (unsigned child_addr, void *buf, unsigned len); Description ----------- This function transfers LEN bytes from the buffer pointed to by BUF in the debugger's data segment to the memory of the debugged process starting at the address CHILD_ADDR. It is used primarily to insert a breakpoint instruction into the debugged process (to trigger a trap when the debuggee's code gets to that point). The companion function `read_child' (*note read_child::.) is usually called before `write_child' to save the original code overwritten by the breakpoint instruction. Return Value ------------ The function return zero if it has successfully transferred the data, non-zero otherwise (e.g., if the address in CHILD_ADDR is outside the limits of the debuggee's code segment. Portability ----------- not ANSI, not POSIX File: libc.info, Node: write_sel_addr, Next: xfree, Prev: write_child, Up: Alphabetical List write_sel_addr ============== Syntax ------ #include <debug/dbgcom.h> void write_sel_addr (unsigned sel, unsigned offset, void *buf, unsigned len); Description ----------- This function transfers LEN bytes from the buffer pointed to by BUF in the data segment whose selector is SEL, at offset OFFSET. The companion function `read_sel_addr' (*note read_sel_addr::.) is usually called before `write_sel_addr' to save the original contents, if needed. Return Value ------------ The function return zero if it has successfully transferred the data, non-zero otherwise (e.g., if the address in OFFSET is outside the limits of the SELs segment). Portability ----------- not ANSI, not POSIX File: libc.info, Node: xfree, Next: xmalloc, Prev: write_sel_addr, Up: Alphabetical List xfree ===== Syntax ------ #include <stdlib.h> void xfree(void *ptr); Description ----------- Frees memory allocated by `xmalloc' (*note xmalloc::.). This function guarantees that a NULL pointer is handled gracefully. Note that, currently, the header `stdlib.h' does *not* declare a prototype for `xfree', because many programs declare its prototype in different and conflicting ways. If you use `xfree' in your own code, you might need to provide your own prototype explicitly. Portability ----------- not ANSI, not POSIX Example ------- void *f = xmalloc(100); xfree(f); File: libc.info, Node: xmalloc, Next: xrealloc, Prev: xfree, Up: Alphabetical List xmalloc ======= Syntax ------ #include <stdlib.h> void *xmalloc(size_t size); Description ----------- This function is just like `malloc' (*note malloc::.), except that if there is no more memory, it prints an error message and exits. Note that, currently, the header `stdlib.h' does *not* declare a prototype for `xmalloc', because many programs declare its prototype in different and conflicting ways. If you use `xmalloc' in your own code, you might need to provide your own prototype explicitly. Return Value ------------ A pointer to the newly allocated memory. Portability ----------- not ANSI, not POSIX Example ------- char *f = xmalloc(100); File: libc.info, Node: xrealloc, Prev: xmalloc, Up: Alphabetical List xrealloc ======== Syntax ------ #include <stdlib.h> void *xrealloc(void *ptr, size_t size); Description ----------- This function is just like `realloc' (*note realloc::.), except that if there is no more memory, it prints an error message and exits. It can also properly handle PTR being `NULL'. Note that, currently, the header `stdlib.h' does *not* declare a prototype for `xrealloc', because many programs declare its prototype in different and conflicting ways. If you use `xrealloc' in your own code, you might need to provide your own prototype explicitly. Return Value ------------ A pointer to a possibly new block. Portability ----------- not ANSI, not POSIX Example ------- char *buf; buf = (char *)xrealloc(buf, new_size); File: libc.info, Node: Unimplemented, Next: Master Index, Prev: Alphabetical List, Up: Top Unimplemented Functions *********************** The DJGPP standard C library is ANSI- and POSIX-compliant, and provides many additional functions for compatibility with Unix/Linux systems. However, some of the functions needed for this compatibility are very hard or impossible to implement using DOS facilities. Therefore, a small number of library functions are really just stubs: they are provided because POSIX requires them to be present in a compliant library, or because they are widely available on Unix systems, but they either always fail, or handle only the trivial cases and fail for all the others. An example of the former behavior is the function `fork': it always returns a failure indication; an example of the latter behavior is the function `mknode': it handles the cases of regular files and existing character devices, but fails for all other file types. This chapter lists all such functions. This list is here for the benefit of programmers who write portable programs or port Unix packages to DJGPP. Each function below is labeled as either "always fails" or "trivial", depending on which of the two classes described above it belongs to. An additional class, labeled "no-op", includes functions which pretend to succeed, but have no real effect, since the underlying functionality is either always available or always ignored. * Menu: * addmntent:: Always fails. * cfgetispeed:: No-op. * cfgetospeed:: No-op. * cfsetispeed:: No-op. * cfsetospeed:: No-op. * chown:: Trivial. * fcntl:: Always fails for all operations except `F_DUPFD' and `F_GETFD'. * fork:: Always fails. * getgrgid:: Trivial. * getgrnam:: Trivial. * getgroups:: Trivial. * getpwnam:: Trivial. * getpwuid:: Trivial. * mkfifo:: Always fails. * mknod:: Trivial. * nice:: No-op. * pipe:: Always fails. * setgid:: Trivial. * setpgid:: Trivial. * setsid:: Trivial. * setuid:: Trivial. * tcdrain:: No-op. * tcsendbreak:: No-op. * tcsetpgrp:: Trivial. * umask:: Trivial. * vfork:: Always fails. * wait:: Always fails. * waitpid:: Always fails. File: libc.info, Node: Master Index, Prev: Unimplemented, Up: Top * Menu: *Note Alphabetical List::. Tag Table: Node: Top177 Node: Introduction606 Node: Functional Categories1921 Node: bios functions2661 Node: conio functions3050 Node: cpu functions3902 Node: ctype functions4446 Node: debugging functions4791 Node: dos functions5359 Node: dpmi functions6091 Node: environment functions10043 Node: file system functions10261 Node: go32 functions11297 Node: io functions11705 Node: locale functions12266 Node: math functions12538 Node: memory functions13098 Node: misc functions13882 Node: mono functions14285 Node: posix functions14491 Node: process functions14709 Node: random number functions15095 Node: shell functions15363 Node: signal functions15556 Node: sound functions16008 Node: startup functions16195 Node: stdio functions16484 Node: string functions17405 Node: termios functions18091 Node: time functions18505 Node: unix functions18929 Node: Alphabetical List19593 Node: _808732094 Node: abort32666 Node: abs33422 Node: access33759 Node: acos34699 Node: acosh35253 Node: addmntent35713 Node: alarm36185 Node: alloca37351 Node: asctime37913 Node: asin39381 Node: asinh39860 Node: assert40437 Node: atan41483 Node: atan242087 Node: atanh43196 Node: atexit43811 Node: atof44577 Node: atoi45185 Node: atol45779 Node: _atold46377 Node: basename47024 Node: bcmp48201 Node: bcopy48853 Node: bdos49375 Node: bdosptr50198 Node: _bios_disk51379 Node: _bios_equiplist56228 Node: _bios_keybrd57489 Node: _bios_memsize60129 Node: _bios_printer60641 Node: _bios_serialcom62004 Node: _bios_timeofday64919 Node: bioscom65946 Node: biosdisk68648 Node: biosequip70757 Node: bioskey72139 Node: biosmemory75175 Node: biosprint75797 Node: biostime76627 Node: blinkvideo77157 Node: brk78155 Node: bsearch78840 Node: bzero80133 Node: calloc80539 Node: cbrt81304 Node: ceil81869 Node: cfgetispeed82261 Node: cfgetospeed82943 Node: cfmakeraw83629 Node: cfree84141 Node: cfsetispeed84598 Node: cfsetospeed85274 Node: cfsetspeed85956 Node: cgets86511 Node: chdir87147 Node: _check_v2_prog87823 Node: chmod91547 Node: _chmod92269 Node: chown93586 Node: chsize94026 Node: cleanup_client94394 Node: _clear8794962 Node: clearerr95342 Node: clock95742 Node: close96302 Node: _close96758 Node: closedir97284 Node: clreol97680 Node: clrscr97983 Node: _conio_kbhit98259 Node: _control8798836 Node: cos103084 Node: cosh104301 Node: cprintf104958 Node: cputs105495 Node: creat105859 Node: _creat106634 Node: _creatnew107454 Node: crlf2nl110386 Node: __crt0_glob_function110820 Node: __crt0_load_environment_file111647 Node: __crt0_setup_arguments112421 Node: _crt0_startup_flags113427 Node: cscanf119031 Node: ctermid119556 Node: ctime120043 Node: delay120509 Node: delline121234 Node: _detect_80387121556 Node: difftime122139 Node: dirname122678 Node: disable123762 Node: div124355 Node: __djgpp_exception_toggle125113 Node: __djgpp_map_physical_memory126068 Node: __djgpp_memory_handle127711 Node: __djgpp_memory_handle_list128398 Node: __djgpp_nearptr_disable129027 Node: __djgpp_nearptr_enable129480 Node: __djgpp_set_ctrl_c131135 Node: __djgpp_set_page_attributes133381 Node: __djgpp_set_sigint_key134734 Node: __djgpp_set_sigquit_key136988 Node: __djgpp_share_flags139213 Node: __djgpp_traceback_exit140856 Node: _djstat_describe_lossage141694 Node: _djstat_fail_bits143922 Node: _djstat_flags147512 Node: _doprnt150688 Node: _dos_close151384 Node: _dos_commit152102 Node: _dos_creat152736 Node: _dos_creatnew154219 Node: _dos_findfirst155715 Node: _dos_findnext157961 Node: _dos_getdate158796 Node: _dos_getdiskfree159606 Node: _dos_getdrive160918 Node: _dos_getfileattr161527 Node: _dos_getftime163229 Node: _dos_gettime165482 Node: _dos_lock166241 Node: _dos_open166667 Node: _dos_read168564 Node: _dos_setdate170009 Node: _dos_setdrive171046 Node: _dos_setfileattr171806 Node: _dos_setftime173064 Node: _dos_settime174839 Node: _dos_unlock175796 Node: _dos_write176232 Node: _doscan177718 Node: _doserrno178470 Node: dosexterr179127 Node: dosmemget184806 Node: dosmemgetb185728 Node: dosmemgetl186695 Node: dosmemgetw187681 Node: dosmemput188663 Node: dosmemputb189552 Node: dosmemputl190493 Node: dosmemputw191444 Node: DPMI Overview192400 Node: DPMI Specification197453 Node: __dpmi_allocate_dos_memory197793 Node: __dpmi_allocate_ldt_descriptors198776 Node: __dpmi_allocate_linear_memory199596 Node: __dpmi_allocate_memory200502 Node: __dpmi_allocate_real_mode_callback201176 Node: __dpmi_allocate_shared_memory202139 Node: __dpmi_allocate_specific_ldt_descriptor203431 Node: __dpmi_clear_debug_watchpoint204130 Node: __dpmi_create_alias_descriptor204790 Node: __dpmi_discard_page_contents205485 Node: __dpmi_free_dos_memory206219 Node: __dpmi_free_ldt_descriptor206938 Node: __dpmi_free_memory207662 Node: __dpmi_free_physical_address_mapping208283 Node: __dpmi_free_real_mode_callback209100 Node: __dpmi_free_serialization_on_shared_memory209797 Node: __dpmi_free_shared_memory210925 Node: __dpmi_get_and_disable_virtual_interrupt_state211737 Node: __dpmi_get_and_enable_virtual_interrupt_state212490 Node: __dpmi_get_and_set_virtual_interrupt_state213256 Node: __dpmi_get_capabilities214110 Node: __dpmi_get_coprocessor_status215322 Node: __dpmi_get_descriptor216488 Node: __dpmi_get_descriptor_access_rights222128 Node: __dpmi_get_extended_exception_handler_vector_pm222953 Node: __dpmi_get_extended_exception_handler_vector_rm223860 Node: __dpmi_get_free_memory_information224760 Node: __dpmi_get_memory_block_size_and_base225549 Node: __dpmi_get_memory_information226316 Node: __dpmi_get_multiple_descriptors228622 Node: __dpmi_get_page_attributes229696 Node: __dpmi_get_page_size231151 Node: __dpmi_get_processor_exception_handler_vector231788 Node: __dpmi_get_protected_mode_interrupt_vector232698 Node: __dpmi_get_raw_mode_switch_addr233539 Node: __dpmi_get_real_mode_interrupt_vector234237 Node: __dpmi_get_segment_base_address235140 Node: __dpmi_get_segment_limit235963 Node: __dpmi_get_selector_increment_value236578 Node: __dpmi_get_state_of_debug_watchpoint237285 Node: __dpmi_get_state_save_restore_addr238061 Node: __dpmi_get_vendor_specific_api_entry_point238783 Node: __dpmi_get_version239530 Node: __dpmi_get_virtual_interrupt_state240447 Node: __dpmi_install_resident_service_provider_callback241119 Node: __dpmi_int242710 Node: __dpmi_lock_linear_region243764 Node: __dpmi_map_conventional_memory_in_memory_block244491 Node: __dpmi_map_device_in_memory_block245450 Node: __dpmi_mark_page_as_demand_paging_candidate246399 Node: __dpmi_mark_real_mode_region_as_pageable247194 Node: __dpmi_physical_address_mapping247991 Node: __dpmi_relock_real_mode_region248805 Node: __dpmi_reset_debug_watchpoint249565 Node: __dpmi_resize_dos_memory250233 Node: __dpmi_resize_linear_memory251033 Node: __dpmi_resize_memory251903 Node: __dpmi_segment_to_descriptor252707 Node: __dpmi_serialize_on_shared_memory253589 Node: __dpmi_set_coprocessor_emulation254975 Node: __dpmi_set_debug_watchpoint256214 Node: __dpmi_set_descriptor256980 Node: __dpmi_set_descriptor_access_rights257848 Node: __dpmi_set_extended_exception_handler_vector_pm259297 Node: __dpmi_set_extended_exception_handler_vector_rm260205 Node: __dpmi_set_multiple_descriptors261104 Node: __dpmi_set_page_attributes262066 Node: __dpmi_set_processor_exception_handler_vector263355 Node: __dpmi_set_protected_mode_interrupt_vector264186 Node: __dpmi_set_real_mode_interrupt_vector265217 Node: __dpmi_set_segment_base_address266071 Node: __dpmi_set_segment_limit266782 Node: __dpmi_simulate_real_mode_interrupt267737 Node: __dpmi_simulate_real_mode_procedure_iret268621 Node: __dpmi_simulate_real_mode_procedure_retf269479 Node: __dpmi_simulate_real_mode_procedure_retf_stack270377 Node: __dpmi_terminate_and_stay_resident271757 Node: __dpmi_unlock_linear_region273155 Node: __dpmi_yield273831 Node: dup274759 Node: dup2275222 Node: _dxe_load275805 Node: ecvt276614 Node: ecvtbuf277224 Node: edi_init278796 Node: enable279692 Node: endgrent280288 Node: endmntent280701 Node: endpwent281119 Node: errno281490 Node: exec*288328 Node: __exit289443 Node: _exit290105 Node: exit290816 Node: exp291374 Node: exp10292219 Node: exp2292985 Node: expm1293749 Node: fabs294691 Node: _far*295176 Node: fclose297833 Node: fcntl298264 Node: fcvt302228 Node: fcvtbuf302834 Node: fdopen304806 Node: feof305397 Node: ferror305848 Node: fflush306320 Node: ffs307482 Node: fgetc307998 Node: fgetgrent308476 Node: fgetpos308827 Node: fgets309274 Node: File System Extensions310087 Node: __file_exists314499 Node: __file_tree_walk315261 Node: filelength318001 Node: fileno318754 Node: findfirst319140 Node: findnext322352 Node: _fixpath322774 Node: floor324225 Node: _flush_disk_cache324665 Node: fmod325478 Node: _fmode326043 Node: fnmatch326540 Node: fnmerge329521 Node: fnsplit330404 Node: fopen331800 Node: fork333991 Node: fpathconf334387 Node: _fpreset334994 Node: fprintf335278 Node: fpurge335673 Node: fputc336227 Node: fputs336652 Node: fread337125 Node: free337644 Node: freopen338080 Node: frexp338674 Node: fscanf339353 Node: fseek339809 Node: fsetpos341401 Node: __FSEXT_add_open_handler341876 Node: __FSEXT_alloc_fd342602 Node: __FSEXT_call_open_handlers344004 Node: __FSEXT_get_data344603 Node: __FSEXT_get_function345345 Node: __FSEXT_set_data346083 Node: __FSEXT_set_function349270 Node: fstat351151 Node: fsync354161 Node: ftell354722 Node: ftime355163 Node: ftruncate355945 Node: ftw356707 Node: _fwalk361177 Node: fwrite361697 Node: gcvt362226 Node: _get_dev_info363289 Node: _get_dos_version366105 Node: _get_volume_info368019 Node: getc370227 Node: getcbrk370670 Node: getch371048 Node: getchar371852 Node: getche372189 Node: getcwd372988 Node: getdate373749 Node: getdfree374298 Node: getdisk375082 Node: getdtablesize375508 Node: getegid375884 Node: getenv376195 Node: geteuid376674 Node: getftime376976 Node: getgid377750 Node: getgrent378052 Node: getgrgid379197 Node: getgrnam379654 Node: getgroups380116 Node: gethostname380506 Node: getitimer381433 Node: getkey382588 Node: getlogin383210 Node: getlongpass383693 Node: getmntent384603 Node: getopt388720 Node: getpagesize390261 Node: getpass390652 Node: getpgrp391519 Node: getpid391876 Node: getpwent392246 Node: getpwnam393785 Node: getpwuid394253 Node: getrlimit394714 Node: getrusage396235 Node: gets397964 Node: gettext398584 Node: gettextinfo398977 Node: gettime399854 Node: gettimeofday400466 Node: getuid401613 Node: getw401910 Node: getwd402437 Node: getxkey402891 Node: glob403504 Node: globfree409902 Node: gmtime410201 Node: _go32_conventional_mem_selector411417 Node: _go32_dpmi_allocate_dos_memory412563 Node: _go32_dpmi_allocate_iret_wrapper413841 Node: _go32_dpmi_allocate_real_mode_callback_iret415107 Node: _go32_dpmi_allocate_real_mode_callback_retf416928 Node: _go32_dpmi_chain_protected_mode_interrupt_vector418194 Node: _go32_dpmi_free_dos_memory419244 Node: _go32_dpmi_free_iret_wrapper420058 Node: _go32_dpmi_free_real_mode_callback420757 Node: _go32_dpmi_get_free_memory_information421538 Node: _go32_dpmi_get_protected_mode_interrupt_vector422893 Node: _go32_dpmi_get_real_mode_interrupt_vector423834 Node: _go32_dpmi_lock_code424617 Node: _go32_dpmi_lock_data425405 Node: _go32_dpmi_remaining_physical_memory426129 Node: _go32_dpmi_remaining_virtual_memory426671 Node: _go32_dpmi_resize_dos_memory427217 Node: _go32_dpmi_set_protected_mode_interrupt_vector428220 Node: _go32_dpmi_set_real_mode_interrupt_vector430164 Node: _go32_dpmi_simulate_fcall430959 Node: _go32_dpmi_simulate_fcall_iret432134 Node: _go32_dpmi_simulate_int433320 Node: _go32_info_block434507 Node: _go32_interrupt_stack_size437930 Node: _go32_my_cs438348 Node: _go32_my_ds438754 Node: _go32_my_ss439130 Node: _go32_rmcb_stack_size439516 Node: _go32_want_ctrl_break439928 Node: _go32_was_ctrl_break_hit440894 Node: gotoxy441725 Node: gppconio_init442094 Node: hasmntopt442621 Node: highvideo443187 Node: htonl443504 Node: htons444060 Node: hypot444609 Node: inb445749 Node: index446058 Node: initstate446659 Node: inp447143 Node: inportb447459 Node: inportl447958 Node: inportsb448475 Node: inportsl448843 Node: inportsw449213 Node: inportw449583 Node: inpw450086 Node: insline450405 Node: insque450760 Node: int386451400 Node: int386x451826 Node: int86452268 Node: int86x456418 Node: intdos457153 Node: intdosx457552 Node: intensevideo457978 Node: _invent_inode459019 Node: ioctl (DOS)460175 Node: ioctl (General description)467358 Node: ioctl (UNIX)467954 Node: _is_executable468398 Node: _is_remote_drive470384 Node: _is_remote_handle471134 Node: isalnum471922 Node: isalpha472284 Node: isascii472616 Node: isatty472977 Node: iscntrl473429 Node: isdigit473782 Node: isgraph474112 Node: islower474508 Node: isprint474851 Node: ispunct475243 Node: isspace475638 Node: isupper476049 Node: isxdigit476406 Node: itoa476796 Node: kbhit477729 Node: kill478548 Node: labs478926 Node: ldexp479246 Node: ldiv479990 Node: _lfn_gen_short_fname480760 Node: _lfn_get_ftime483076 Node: __libc_termios_init484776 Node: libm485352 Node: link491450 Node: llabs491988 Node: lldiv492330 Node: load_npx493130 Node: localeconv494510 Node: localtime497389 Node: lock497902 Node: log498714 Node: log10499223 Node: log1p499739 Node: log2500336 Node: longjmp500858 Node: lowvideo501673 Node: lseek501984 Node: malloc502776 Node: matherr503579 Node: mblen507698 Node: mbstowcs508317 Node: mbtowc508858 Node: memccpy509485 Node: memchr510503 Node: memcmp511035 Node: memcpy511478 Node: memicmp512045 Node: memmove512639 Node: memset513231 Node: mkdir513852 Node: mkfifo514554 Node: mknod514922 Node: mkstemp515760 Node: mktemp516727 Node: mktime517540 Node: modf519146 Node: modfl519868 Node: _mono_clear520327 Node: _mono_printf520631 Node: _mono_putc520987 Node: movedata521313 Node: movedatab522952 Node: movedatal523338 Node: movedataw523776 Node: movetext524213 Node: mprotect524651 Node: _my_cs525847 Node: _my_ds526225 Node: _my_ss526601 Node: nice526975 Node: normvideo527349 Node: nosound527674 Node: ntohl527946 Node: ntohs528497 Node: open529042 Node: _open531443 Node: opendir532202 Node: outb534125 Node: outp534452 Node: outportb534781 Node: outportl535242 Node: outportsb535708 Node: outportsl536075 Node: outportsw536444 Node: outportw536814 Node: outpw537279 Node: pathconf537616 Node: pause539790 Node: pclose540161 Node: perror540775 Node: pipe541352 Node: popen541695 Node: pow542997 Node: pow10544102 Node: pow2544871 Node: powi545631 Node: _preserve_fncase546439 Node: printf548028 Node: psignal551440 Node: _put_path552228 Node: putc558569 Node: putch558995 Node: putchar559506 Node: putenv559926 Node: puts560805 Node: puttext561243 Node: putw561632 Node: qsort562151 Node: raise563696 Node: rand564088 Node: rand48565380 Node: random567623 Node: rawclock568077 Node: read568550 Node: _read569233 Node: read_child569837 Node: read_sel_addr570716 Node: readdir571433 Node: realloc572482 Node: redir_cmdline_delete573339 Node: redir_cmdline_parse574355 Node: redir_debug_init576631 Node: redir_to_child581582 Node: redir_to_debugger583113 Node: regcomp584611 Node: regerror599364 Node: regexec601733 Node: regfree607640 Node: remove608156 Node: remque608660 Node: _rename609269 Node: rename610586 Node: rewind612175 Node: rewinddir612597 Node: rindex613084 Node: rmdir613683 Node: run_child614138 Node: save_npx617020 Node: sbrk618383 Node: scanf619316 Node: Screen Variables626568 Node: ScreenClear627703 Node: ScreenCols628219 Node: ScreenGetChar628928 Node: ScreenGetCursor629983 Node: ScreenMode630562 Node: ScreenPutChar631066 Node: ScreenPutString631754 Node: ScreenRetrieve632543 Node: ScreenRows633298 Node: ScreenSetCursor633913 Node: ScreenUpdate634480 Node: ScreenUpdateLine635043 Node: ScreenVisualBell635577 Node: searchpath636113 Node: seekdir637868 Node: select638540 Node: _set_screen_lines644399 Node: setbuf645567 Node: setbuffer646409 Node: setcbrk647272 Node: _setcursortype647700 Node: setdate648185 Node: setdisk648667 Node: setenv649159 Node: setftime649752 Node: setgid650571 Node: setgrent651034 Node: setitimer651486 Node: setjmp655635 Node: setlinebuf656456 Node: setlocale657168 Node: setmntent658336 Node: setmode659594 Node: setpgid661017 Node: setpwent661342 Node: setrlimit661745 Node: setsid662244 Node: setstate662628 Node: settime663057 Node: settimeofday663538 Node: setuid664038 Node: setvbuf664503 Node: sigaction665597 Node: sigaddset667121 Node: sigdelset667615 Node: sigemptyset668120 Node: sigfillset668729 Node: sigismember669648 Node: siglongjmp670212 Node: signal670510 Node: sigpending679640 Node: sigprocmask680913 Node: sigsetjmp684707 Node: sin685002 Node: sincos686212 Node: sinh687192 Node: sleep687902 Node: sound688338 Node: spawn*688690 Node: sprintf694244 Node: sqrt694657 Node: srand695072 Node: srandom695592 Node: sscanf696118 Node: stackavail696595 Node: stat697012 Node: statfs701968 Node: _status87703091 Node: _stklen704248 Node: stpcpy704705 Node: strcasecmp705118 Node: strcat705644 Node: strchr706062 Node: strcmp706609 Node: strcoll707134 Node: strcpy707708 Node: strcspn708094 Node: strdup708747 Node: strerror709359 Node: strftime709877 Node: stricmp712702 Node: strlen713215 Node: strlwr713663 Node: strncasecmp714110 Node: strncat714733 Node: strncmp715170 Node: strncpy715740 Node: strnicmp716172 Node: strpbrk716781 Node: strrchr717299 Node: strsep717787 Node: strspn718720 Node: strstr719362 Node: strtod719829 Node: strtok720665 Node: strtol721498 Node: _strtold722460 Node: strtoll723058 Node: strtoul724011 Node: strtoull724571 Node: strupr725151 Node: strxfrm725580 Node: swab726212 Node: symlink726830 Node: syms_init728429 Node: syms_line2val729371 Node: syms_listwild730486 Node: syms_module732789 Node: syms_name2val733521 Node: syms_val2line735810 Node: syms_val2name736894 Node: sync738291 Node: sys_errlist738913 Node: sys_nerr739330 Node: sysconf739774 Node: system740623 Node: tan749123 Node: tanh749742 Node: tcdrain750279 Node: tcflow750885 Node: tcflush751767 Node: tcgetattr752492 Node: tcgetpgrp753227 Node: tcsendbreak753949 Node: tcsetattr754522 Node: tcsetpgrp755373 Node: tell756298 Node: telldir756711 Node: tempnam757292 Node: Termios functions759577 Node: textattr766282 Node: textbackground766986 Node: textcolor767340 Node: textmode767679 Node: time768466 Node: times768872 Node: tmpfile769823 Node: tmpnam770384 Node: toascii771989 Node: tolower772444 Node: toupper772909 Node: _truename773375 Node: truncate775373 Node: ttyname775818 Node: tzset776246 Node: tzsetwall776757 Node: uclock777232 Node: umask778934 Node: uname779241 Node: ungetc780090 Node: ungetch780588 Node: unlink780990 Node: unlock781403 Node: _use_lfn781799 Node: usleep785070 Node: utime785874 Node: utimes786850 Node: v2loadimage788135 Node: varargs790284 Node: vfork792302 Node: vfprintf792707 Node: vfscanf793379 Node: vprintf793866 Node: vscanf794317 Node: vsprintf794808 Node: vsscanf795279 Node: wait795794 Node: waitpid796626 Node: wcstombs797262 Node: wctomb797765 Node: wherex798264 Node: wherey798566 Node: wild798863 Node: window799688 Node: write800103 Node: _write801922 Node: write_child803711 Node: write_sel_addr804727 Node: xfree805537 Node: xmalloc806243 Node: xrealloc807018 Node: Unimplemented807869 Node: Master Index810505 End Tag Table